@sutraa/kalpa-agent

@sutraa/kalpa-agent exposes a narrow, read-only inspection surface for an already-created Kalpa runtime. It also validates whether a proposed entity/capability target exists. It does not modify a manifest, dispatch commands, write files, or apply patches.

npm install @sutraa/kalpa-agent

Inspect a runtime

Create and use a runtime with @sutraa/kalpa-runtime, then pass it to inspectRuntime. Select the active representation explicitly as dom or canvas.

import { inspectRuntime, validatePatchProposal } from "@sutraa/kalpa-agent";

const inspection = inspectRuntime(runtime, "dom");

console.log(inspection.manifest.entities);
console.log(inspection.state);
console.log(inspection.eventTrace);
console.log(inspection.diagnostics);
console.log(inspection.provenance.mutationMode); // "read-only"

AgentInspection contains the semantic graph snapshot, state, events, diagnostics, a renderer-decision summary, and provenance. It is appropriate for a review tool or an agent that needs structured visibility into the running experience without being granted mutation authority.

Validate a proposal target

validatePatchProposal checks only two facts: the proposed entity exists in the runtime graph, and it declares the requested capability. It does not apply a change or validate arbitrary source edits.

const proposal = validatePatchProposal(runtime, {
  entityId: "pump",
  capability: "inspectable",
});

if (proposal.valid) {
  console.log(proposal.reason);
} else {
  console.error(proposal.reason);
}

| Return | Meaning | | --- | --- | | { valid: true } | existing entity declares the requested capability. | | { valid: false } | entity is absent or capability is not declared. |

Scope boundary

The package validates a narrow proposal target, not a patch file, rendering outcome, authorization policy, or deployment. It intentionally contains no autonomous action, state mutation, command dispatch, source editing, or network operation.

License

MIT. Requires Node.js 18 or later.