@maiaos/protocol 0.1.0-canary.1

package/README.md

@@ -0,0 +1,166 @@
+# `@maiaos/protocol`
+
+[![npm canary](https://img.shields.io/npm/v/@maiaos/protocol/canary?label=npm%20canary)](https://www.npmjs.com/package/@maiaos/protocol)
+
+The operation registry and Effect Schema contracts that Maia Node and every
+Maia OS client agree on: operation IDs, request and response envelopes, errors,
+receipts, and the MCP tool definitions that AI coding agents such as Claude
+Code and Codex call.
+
+`@maiaos/protocol` is the single source of truth for Maia's wire contracts. The
+Node validates every request against it, and `@maiaos/sdk`, the `maia` CLI, the
+`maia mcp` MCP server and the Desktop client are generated from it or checked
+against it. Use it to validate Maia payloads or to build tooling over the
+registry. To talk to a running Node, use [`@maiaos/sdk`](../sdk/README.md).
+
+## Install
+
+```sh
+pnpm add @maiaos/protocol@canary
+```
+
+Only `canary` builds are published. They are not release-qualified and can lag
+the source in this repository. npm also points the automatic `latest` tag at a
+canary build; no stable version exists.
+
+## Example
+
+```ts
+import {
+  MAIA_PROTOCOL_VERSION,
+  projectListParametersSchema,
+} from "@maiaos/protocol";
+
+const parsed = projectListParametersSchema.safeParse({
+  afterCursor: "0",
+  limit: 20,
+});
+if (parsed.success) console.log(MAIA_PROTOCOL_VERSION, parsed.data.limit);
+// maia.protocol/v1alpha1 20
+```
+
+## Key concepts
+
+- **Operations.** Each Node operation has a stable ID (`session.create`,
+  `turn.wait`, `receipt.get`), strict parameter and result schemas, an
+  exposure class for Agent requests (`eligible`, `human-only` or
+  `unsupported`) and receipt rules. New operations must be classified to
+  compile.
+- **Runtime schemas.** Every schema exposes `parse` and `safeParse`
+  (`RuntimeSchema<T>`), and its TypeScript type is inferred from the same
+  schema. Effect Schema is the implementation; Effect types do not leak into
+  the public API.
+- **Envelopes, errors and receipts.** Envelopes carry the
+  `maia.protocol/v1alpha1` identifier. Errors have a stable `code` and a
+  `retryable` flag; a `saturated` error may add `saturation`: `admission`
+  (the Node's request slots, free within moments) or `account` (an account's
+  Session slots or vendor limit). Errors decode strictly like every wire
+  schema: a client that reads an error with a key it does not know (a peer
+  of another version) rejects the answer as invalid, and a bridge failure
+  frame then keeps only the bridge's own code. A mutation's receipt binds
+  actor, command ID, method, target and revision, so a retry with the same
+  command ID replays the first result.
+- **Node API transport.** Unary operations use `POST /api/v1/operations` on
+  `http://127.0.0.1:<port>`; observations use the `/api/v1/observations`
+  WebSocket with the `maia.node.observations.v1` subprotocol, which carries
+  `observe.events` and `session.attach`. The discovery descriptor admits only
+  that loopback origin.
+- **Session item stream (S12b).** `SessionStreamRecord`, `SessionItem` and
+  the `session.attach` subscribe and frame schemas
+  (`SESSION_STREAM_SCHEMA_VERSION`, `maia.session-stream/v1`) are additions to
+  `v1alpha1`. A record carries its Session, turn, owner `sequence` and Node
+  `epoch`; `item.delta` is live-only.
+- **SSH stdio bridge.** `maia.node.stdio/v1` carries the same request and
+  response envelopes, one JSON object per line, over `ssh` to a remote Node's
+  `maia-node bridge`, after a `ready` frame holding that Node's status
+  (`bridgeServerFrameSchema`, `bridgeRequestFrameSchema`); the remote Node
+  registry is `node.remote.*`.
+- **Emergency holds.** The human-only `hold.place.preview`/`confirm`,
+  `hold.release.preview`/`confirm` and `hold.list` operations name 1–64 exact
+  Project or account targets (no wildcard). Work refused by a hold fails with
+  the error code `held` (`HOLD_ADMISSION_ERROR_CODE`), and `session.stopped`
+  may carry the `holdId` that stopped the Session. Both are additions to
+  `v1alpha1`: a reader built before them rejects a `session.stopped` event
+  that names a hold.
+- **Session roles and guards.** `SESSION_ROLE_OPERATIONS` lists what a
+  `worker` and an `orchestrator` Session reach with its own credential
+  (`Authorization: Maia-Session`, scheme `NODE_API_SESSION_CREDENTIAL_SCHEME`);
+  both roles admit `session.list`, scoped by the Node to the credential's
+  Project before pagination, and anything else outside the role fails
+  `role_denied`. This adds no request or response fields; older Nodes refuse
+  that Session-authenticated read. `project.guard.show` and the human-only
+  `project.guard.preview` and `project.guard.confirm` read and replace a
+  Project's four fan-out limits, each
+  of which trips with its own code in `SESSION_GUARD_ERROR_CODES`.
+- **References and titles.** `reference.resolve` turns an ID, an ID prefix
+  (`MIN_REFERENCE_PREFIX_LENGTH` hexadecimal digits), a name or a Session title
+  into one exact ID or up to `MAX_REFERENCE_CANDIDATES` candidates, or, without
+  a reference, the Project or Workspace whose registered folder contains a
+  path. `Session.title` (at most `MAX_SESSION_TITLE_LENGTH` characters, one
+  line) is an optional field, `session.create` takes one, and
+  `session.rename` with its `session.renamed` event changes it. All are
+  additions to `v1alpha1`: a reader built before them rejects a titled Session.
+- **Coordinator tools.** `coordinatorToolDefinitions()` returns the 43 MCP
+  tools that `maia mcp` serves (`session_create`, `turn_send`, `turn_wait`,
+  ...), with input schemas generated from the operation schemas.
+
+| Entry point                                     | Contents                                                        |
+| ----------------------------------------------- | --------------------------------------------------------------- |
+| `@maiaos/protocol`                              | Operation registry, envelopes, errors, receipts, domain schemas |
+| `@maiaos/protocol/agent-definition`             | Agent definition schema, canonical digest encoding, eligibility |
+| `@maiaos/protocol/node-profile`                 | Node.js-only profile validation and host paths                  |
+| `@maiaos/protocol/feature-registry`             | Static registry binding features to SDK, CLI and Node handlers  |
+| `@maiaos/protocol/voice-orchestrator`           | Voice orchestrator prompt and tool contracts                    |
+| `@maiaos/protocol/voice-pi-relay`               | Voice-to-Pi relay preview, relay and reconcile contracts        |
+| `@maiaos/protocol/execution-candidate`          | Execution, worktree and checkpoint candidate contracts          |
+| `@maiaos/protocol/invocation-context-candidate` | Invocation context candidate contracts                          |
+
+## Status
+
+Source-implemented candidate. A registered operation is not a product claim:
+many are release-disabled, and `maia help --json` reports which commands are
+implemented and which are source candidates. A generated public operation
+catalog and device-capability schemas are planned, not exported.
+
+## How it fits in Maia
+
+```text
+@maiaos/protocol ──► @maiaos/sdk ──► maia CLI, maia mcp, Desktop, Expo client
+        │
+        └──────────► Maia Node (validates, authorizes, stores, writes receipts)
+```
+
+The protocol grants nothing by itself: a schema checks shape, and Maia Node
+enforces authentication, revisions, confirmation and receipts. See
+[`ARCHITECTURE.md`](../../ARCHITECTURE.md).
+
+## Development
+
+```sh
+pnpm --filter @maiaos/protocol build
+pnpm --filter @maiaos/protocol lint
+pnpm --filter @maiaos/protocol typecheck
+pnpm --filter @maiaos/protocol test
+```
+
+Source is organized in concept folders (`envelope/`, `session/`,
+`coordinator-tool/`, ...), each with an export-only `index.ts` and colocated
+tests, per the [source organization contract](../../docs/source-organization.md).
+A scope that shares Effect Schema values with other scopes adds one private
+`effect-schema.ts` entry; no `index.ts` exports Effect
+([D-062](../../docs/decisions.md#d-062)).
+
+## Documentation
+
+- [Normative contracts](../../docs/reference/contracts.md): IDs, versioning,
+  operations, events and receipts
+- Module contracts: [coordinator tools](./src/coordinator-tool/README.md),
+  [connections](./src/connection/README.md),
+  [interactions](./src/interaction/README.md),
+  [presentation](./src/presentation/README.md) and
+  [harnesses](./src/harness/README.md)
+- [CLI reference](../../docs/reference/cli.md)
+
+## License
+
+No license has been published yet. All rights reserved.

package/dist/agent/definition.d.ts

@@ -0,0 +1,64 @@
+import type { InferRuntimeSchema } from "../runtime-schema/index.js";
+export { AGENT_REQUEST_OPERATION_IDS, LOCAL_NODE_METHOD_EXPOSURE, } from "../local-node/node-api/index.js";
+export { type AgentPermissionPreflight, agentPermissionPreflightSchema, } from "./permission-preflight.js";
+export { type AgentWorkerOperationRequest, agentWorkerOperationRequestSchema, type AgentWorkerOperationResponse, agentWorkerOperationResponseSchema, } from "./worker-operation.js";
+export declare const AGENT_DEFINITION_SCHEMA_VERSION = "maia.agent-definition/v1";
+export declare const agentDefinitionReferenceSchema: import("../runtime-schema/runtime-schema.js").RuntimeSchema<{
+    readonly contentDigest: string;
+    readonly key: string;
+    readonly version: string;
+}>;
+export type AgentDefinitionReference = InferRuntimeSchema<typeof agentDefinitionReferenceSchema>;
+export declare const agentDefinitionSchema: import("../runtime-schema/runtime-schema.js").RuntimeSchema<{
+    readonly key: string;
+    readonly name: string;
+    readonly prompt: string;
+    readonly provenance: {
+        readonly kind: "distribution" | "user";
+        readonly source: {
+            readonly contentDigest: string;
+            readonly key: string;
+            readonly version: string;
+        };
+    };
+    readonly requestedOperationIds: readonly ("approval.list" | "approval.respond" | "approval.show" | "connection.capacity.set" | "connection.create" | "connection.detect" | "connection.gateway.create" | "connection.list" | "connection.login.start" | "connection.models.list" | "connection.show" | "connection.state.set" | "connection.system.confirm" | "connection.system.preview" | "connection.usage.show" | "container.create.confirm" | "container.create.preview" | "container.index.list" | "container.list" | "container.rename.confirm" | "container.rename.preview" | "container.show" | "context.show" | "discovery.sessions.list" | "execution.catalog.get" | "execution.checkpoint.create" | "execution.checkpoint.show" | "execution.command.run" | "execution.file.read" | "execution.placement.create" | "execution.placement.show" | "execution.relocation.apply" | "execution.relocation.plan" | "execution.relocation.reconcile" | "execution.relocation.show" | "execution.worktree.create" | "execution.worktree.import" | "execution.worktree.reconcile" | "execution.worktree.remove.apply" | "execution.worktree.remove.plan" | "execution.worktree.status" | "harness.installed.list" | "hold.list" | "hold.place.confirm" | "hold.place.preview" | "hold.release.confirm" | "hold.release.preview" | "integration.apply.claude-code" | "integration.apply.codex" | "integration.apply.pi-rpc" | "integration.plan.claude-code" | "integration.plan.codex" | "integration.plan.pi-rpc" | "integration.remove.claude-code" | "integration.remove.codex" | "integration.remove.pi-rpc" | "integration.status.claude-code" | "integration.status.codex" | "integration.status.pi-rpc" | "interaction.cancel" | "interaction.create" | "interaction.list" | "interaction.respond" | "interaction.show" | "monitor.bootstrap.create" | "node.remote.install.confirm" | "node.remote.install.preview" | "node.remote.list" | "node.remote.remove.confirm" | "node.remote.remove.preview" | "node.shutdown" | "node.status" | "port.lease.acquire" | "port.lease.list" | "port.lease.release" | "port.lease.renew" | "presentation.catalog.show" | "presentation.project-list.show" | "presentation.session-list.show" | "presentation.workspace-directory.show" | "project.context.list" | "project.context.record" | "project.context.show" | "project.create.confirm" | "project.create.preview" | "project.guard.confirm" | "project.guard.preview" | "project.guard.show" | "project.list" | "project.register" | "project.rename.confirm" | "project.rename.preview" | "project.show" | "provider.pool.list" | "receipt.get" | "receipt.list" | "reference.resolve" | "run.create" | "run.dispatch.settle-terminal" | "run.dispatch.show" | "run.inbox.ack" | "run.inbox.check" | "run.ledger.create" | "run.ledger.list" | "run.ledger.task.dispatch" | "run.ledger.task.list" | "run.ledger.task.settle" | "run.ledger.task.show" | "run.list" | "run.question.cancel" | "run.question.open" | "run.question.reply" | "run.show" | "run.task.list" | "run.task.show" | "runtime.probe" | "session.adopt.confirm" | "session.adopt.preview" | "session.agent-permission.confirm" | "session.agent-permission.preview" | "session.archive" | "session.create" | "session.diff" | "session.events.list" | "session.history.read" | "session.inbox.ack" | "session.inbox.check" | "session.list" | "session.message.send" | "session.observe" | "session.rename" | "session.resume" | "session.show" | "session.spawn" | "session.start" | "session.stop" | "terminal.controller.acquire" | "terminal.controller.release" | "terminal.controller.renew" | "terminal.controller.request" | "terminal.controller.request.show" | "terminal.create" | "terminal.events.list" | "terminal.input.write" | "terminal.list" | "terminal.mutation.reconcile" | "terminal.observer.attach" | "terminal.observer.check" | "terminal.observer.detach" | "terminal.observer.resync" | "terminal.read" | "terminal.session.close" | "terminal.session.delete" | "terminal.session.resize" | "terminal.session.restart" | "terminal.session.signal" | "terminal.show" | "turn.interrupt" | "turn.send" | "turn.show" | "turn.wait" | "voice.managed-turn.confirm" | "voice.managed-turn.preview" | "voice.orchestrator.context.show" | "voice.orchestrator.tool.call" | "voice.pi.relay" | "voice.pi.relay.preview" | "voice.pi.relay.reconcile" | "workspace.context.show" | "workspace.execution.configure" | "workspace.execution.show" | "workspace.list" | "workspace.membership.attach" | "workspace.repository.attach" | "workspace.select" | "workspace.show")[];
+    readonly schemaVersion: "maia.agent-definition/v1";
+    readonly skillRefs: readonly {
+        readonly contentDigest: string;
+        readonly key: string;
+        readonly version: string;
+    }[];
+    readonly version: string;
+}>;
+export type AgentDefinition = InferRuntimeSchema<typeof agentDefinitionSchema>;
+export declare const agentDefinitionSnapshotSchema: import("../runtime-schema/runtime-schema.js").RuntimeSchema<{
+    readonly definition: {
+        readonly key: string;
+        readonly name: string;
+        readonly prompt: string;
+        readonly provenance: {
+            readonly kind: "distribution" | "user";
+            readonly source: {
+                readonly contentDigest: string;
+                readonly key: string;
+                readonly version: string;
+            };
+        };
+        readonly requestedOperationIds: readonly ("approval.list" | "approval.respond" | "approval.show" | "connection.capacity.set" | "connection.create" | "connection.detect" | "connection.gateway.create" | "connection.list" | "connection.login.start" | "connection.models.list" | "connection.show" | "connection.state.set" | "connection.system.confirm" | "connection.system.preview" | "connection.usage.show" | "container.create.confirm" | "container.create.preview" | "container.index.list" | "container.list" | "container.rename.confirm" | "container.rename.preview" | "container.show" | "context.show" | "discovery.sessions.list" | "execution.catalog.get" | "execution.checkpoint.create" | "execution.checkpoint.show" | "execution.command.run" | "execution.file.read" | "execution.placement.create" | "execution.placement.show" | "execution.relocation.apply" | "execution.relocation.plan" | "execution.relocation.reconcile" | "execution.relocation.show" | "execution.worktree.create" | "execution.worktree.import" | "execution.worktree.reconcile" | "execution.worktree.remove.apply" | "execution.worktree.remove.plan" | "execution.worktree.status" | "harness.installed.list" | "hold.list" | "hold.place.confirm" | "hold.place.preview" | "hold.release.confirm" | "hold.release.preview" | "integration.apply.claude-code" | "integration.apply.codex" | "integration.apply.pi-rpc" | "integration.plan.claude-code" | "integration.plan.codex" | "integration.plan.pi-rpc" | "integration.remove.claude-code" | "integration.remove.codex" | "integration.remove.pi-rpc" | "integration.status.claude-code" | "integration.status.codex" | "integration.status.pi-rpc" | "interaction.cancel" | "interaction.create" | "interaction.list" | "interaction.respond" | "interaction.show" | "monitor.bootstrap.create" | "node.remote.install.confirm" | "node.remote.install.preview" | "node.remote.list" | "node.remote.remove.confirm" | "node.remote.remove.preview" | "node.shutdown" | "node.status" | "port.lease.acquire" | "port.lease.list" | "port.lease.release" | "port.lease.renew" | "presentation.catalog.show" | "presentation.project-list.show" | "presentation.session-list.show" | "presentation.workspace-directory.show" | "project.context.list" | "project.context.record" | "project.context.show" | "project.create.confirm" | "project.create.preview" | "project.guard.confirm" | "project.guard.preview" | "project.guard.show" | "project.list" | "project.register" | "project.rename.confirm" | "project.rename.preview" | "project.show" | "provider.pool.list" | "receipt.get" | "receipt.list" | "reference.resolve" | "run.create" | "run.dispatch.settle-terminal" | "run.dispatch.show" | "run.inbox.ack" | "run.inbox.check" | "run.ledger.create" | "run.ledger.list" | "run.ledger.task.dispatch" | "run.ledger.task.list" | "run.ledger.task.settle" | "run.ledger.task.show" | "run.list" | "run.question.cancel" | "run.question.open" | "run.question.reply" | "run.show" | "run.task.list" | "run.task.show" | "runtime.probe" | "session.adopt.confirm" | "session.adopt.preview" | "session.agent-permission.confirm" | "session.agent-permission.preview" | "session.archive" | "session.create" | "session.diff" | "session.events.list" | "session.history.read" | "session.inbox.ack" | "session.inbox.check" | "session.list" | "session.message.send" | "session.observe" | "session.rename" | "session.resume" | "session.show" | "session.spawn" | "session.start" | "session.stop" | "terminal.controller.acquire" | "terminal.controller.release" | "terminal.controller.renew" | "terminal.controller.request" | "terminal.controller.request.show" | "terminal.create" | "terminal.events.list" | "terminal.input.write" | "terminal.list" | "terminal.mutation.reconcile" | "terminal.observer.attach" | "terminal.observer.check" | "terminal.observer.detach" | "terminal.observer.resync" | "terminal.read" | "terminal.session.close" | "terminal.session.delete" | "terminal.session.resize" | "terminal.session.restart" | "terminal.session.signal" | "terminal.show" | "turn.interrupt" | "turn.send" | "turn.show" | "turn.wait" | "voice.managed-turn.confirm" | "voice.managed-turn.preview" | "voice.orchestrator.context.show" | "voice.orchestrator.tool.call" | "voice.pi.relay" | "voice.pi.relay.preview" | "voice.pi.relay.reconcile" | "workspace.context.show" | "workspace.execution.configure" | "workspace.execution.show" | "workspace.list" | "workspace.membership.attach" | "workspace.repository.attach" | "workspace.select" | "workspace.show")[];
+        readonly schemaVersion: "maia.agent-definition/v1";
+        readonly skillRefs: readonly {
+            readonly contentDigest: string;
+            readonly key: string;
+            readonly version: string;
+        }[];
+        readonly version: string;
+    };
+    readonly reference: {
+        readonly contentDigest: string;
+        readonly key: string;
+        readonly version: string;
+    };
+}>;
+export type AgentDefinitionSnapshot = InferRuntimeSchema<typeof agentDefinitionSnapshotSchema>;
+export declare const encodeAgentDefinition: (input: AgentDefinition) => string;
+//# sourceMappingURL=definition.d.ts.map

package/dist/agent/definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../src/agent/definition.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAIrE,OAAO,EACL,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,KAAK,wBAAwB,EAC7B,8BAA8B,GAC/B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,KAAK,2BAA2B,EAChC,iCAAiC,EACjC,KAAK,4BAA4B,EACjC,kCAAkC,GACnC,MAAM,uBAAuB,CAAC;AAE/B,eAAO,MAAM,+BAA+B,6BAA6B,CAAC;AA8C1E,eAAO,MAAM,8BAA8B;;;;EACP,CAAC;AACrC,MAAM,MAAM,wBAAwB,GAAG,kBAAkB,CACvD,OAAO,8BAA8B,CACtC,CAAC;AACF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;EAAsC,CAAC;AACzE,MAAM,MAAM,eAAe,GAAG,kBAAkB,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE/E,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQzC,CAAC;AACF,MAAM,MAAM,uBAAuB,GAAG,kBAAkB,CACtD,OAAO,6BAA6B,CACrC,CAAC;AAIF,eAAO,MAAM,qBAAqB,UAAW,eAAe,KAAG,MAa9D,CAAC"}

package/dist/agent/definition.js

@@ -0,0 +1,45 @@
+import * as Schema from "effect/Schema";
+import { LOCAL_NODE_REQUEST_METHODS } from "../local-node/node-api/index.js";
+import { makeEffectRuntimeSchema } from "../runtime-schema/effect-schema.js";
+import { agentDefinitionReferenceEffectSchema } from "./effect-schema.js";
+export { AGENT_REQUEST_OPERATION_IDS, LOCAL_NODE_METHOD_EXPOSURE, } from "../local-node/node-api/index.js";
+export { agentPermissionPreflightSchema, } from "./permission-preflight.js";
+export { agentWorkerOperationRequestSchema, agentWorkerOperationResponseSchema, } from "./worker-operation.js";
+export const AGENT_DEFINITION_SCHEMA_VERSION = "maia.agent-definition/v1";
+const logicalKey = Schema.String.check(Schema.isBetweenLength(1, 128), Schema.isPattern(/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/u));
+const version = Schema.String.check(Schema.isBetweenLength(1, 128), Schema.isPattern(/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/u));
+const boundedText = (maximum) => Schema.String.check(Schema.isBetweenLength(1, maximum), Schema.isPattern(/^[^\0]*$/u), Schema.makeFilter((value) => value.trim().length > 0 &&
+    new TextEncoder().encode(value).byteLength <= maximum));
+const reference = agentDefinitionReferenceEffectSchema;
+const definition = Schema.Struct({
+    key: logicalKey,
+    name: boundedText(128),
+    prompt: boundedText(16_384),
+    provenance: Schema.Struct({
+        kind: Schema.Literals(["distribution", "user"]),
+        source: reference,
+    }),
+    requestedOperationIds: Schema.Array(Schema.Literals(LOCAL_NODE_REQUEST_METHODS)).check(Schema.isMaxLength(32), Schema.makeFilter((values) => new Set(values).size === values.length)),
+    schemaVersion: Schema.Literal(AGENT_DEFINITION_SCHEMA_VERSION),
+    skillRefs: Schema.Array(reference).check(Schema.isMaxLength(32), Schema.makeFilter((values) => new Set(values.map((value) => value.key)).size === values.length)),
+    version,
+});
+export const agentDefinitionReferenceSchema = makeEffectRuntimeSchema(reference);
+export const agentDefinitionSchema = makeEffectRuntimeSchema(definition);
+export const agentDefinitionSnapshotSchema = makeEffectRuntimeSchema(Schema.Struct({ definition, reference }).check(Schema.makeFilter((value) => value.reference.key === value.definition.key &&
+    value.reference.version === value.definition.version)));
+// Canonical JSON sorts object keys and preserves array order and string bytes.
+// The Node resolver must hash these UTF-8 bytes and verify the reference digest.
+export const encodeAgentDefinition = (input) => {
+    const parsed = agentDefinitionSchema.parse(input);
+    return JSON.stringify(parsed, (_key, value) => {
+        if (typeof value !== "object" || value === null || Array.isArray(value)) {
+            return value;
+        }
+        const object = value;
+        return Object.fromEntries(Object.keys(object)
+            .sort()
+            .map((key) => [key, object[key]]));
+    });
+};
+//# sourceMappingURL=definition.js.map

package/dist/agent/definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../src/agent/definition.ts"],"names":[],"mappings":"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"}

package/dist/agent/effect-schema.d.ts

@@ -0,0 +1,7 @@
+import * as Schema from "effect/Schema";
+export declare const agentDefinitionReferenceEffectSchema: Schema.Struct<{
+    readonly contentDigest: Schema.String;
+    readonly key: Schema.String;
+    readonly version: Schema.String;
+}>;
+//# sourceMappingURL=effect-schema.d.ts.map

package/dist/agent/effect-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect-schema.d.ts","sourceRoot":"","sources":["../../src/agent/effect-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,eAAO,MAAM,oCAAoC;;;;EAY/C,CAAC"}

package/dist/agent/effect-schema.js

@@ -0,0 +1,7 @@
+import * as Schema from "effect/Schema";
+export const agentDefinitionReferenceEffectSchema = Schema.Struct({
+    contentDigest: Schema.String.check(Schema.isPattern(/^sha256:[a-f0-9]{64}$/u)),
+    key: Schema.String.check(Schema.isBetweenLength(1, 128), Schema.isPattern(/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/u)),
+    version: Schema.String.check(Schema.isBetweenLength(1, 128), Schema.isPattern(/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/u)),
+});
+//# sourceMappingURL=effect-schema.js.map

package/dist/agent/effect-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect-schema.js","sourceRoot":"","sources":["../../src/agent/effect-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,MAAM,CAAC,MAAM,oCAAoC,GAAG,MAAM,CAAC,MAAM,CAAC;IAChE,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAChC,MAAM,CAAC,SAAS,CAAC,wBAAwB,CAAC,CAC3C;IACD,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CACtB,MAAM,CAAC,eAAe,CAAC,CAAC,EAAE,GAAG,CAAC,EAC9B,MAAM,CAAC,SAAS,CAAC,+BAA+B,CAAC,CAClD;IACD,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAC1B,MAAM,CAAC,eAAe,CAAC,CAAC,EAAE,GAAG,CAAC,EAC9B,MAAM,CAAC,SAAS,CAAC,+BAA+B,CAAC,CAClD;CACF,CAAC,CAAC"}

package/dist/agent/index.d.ts

@@ -0,0 +1,4 @@
+export { AGENT_DEFINITION_SCHEMA_VERSION, AGENT_REQUEST_OPERATION_IDS, type AgentDefinition, type AgentDefinitionReference, agentDefinitionReferenceSchema, agentDefinitionSchema, type AgentDefinitionSnapshot, agentDefinitionSnapshotSchema, encodeAgentDefinition, LOCAL_NODE_METHOD_EXPOSURE, } from "./definition.js";
+export { type AgentPermissionPreflight, agentPermissionPreflightSchema, } from "./permission-preflight.js";
+export { type AgentWorkerOperationRequest, agentWorkerOperationRequestSchema, type AgentWorkerOperationResponse, agentWorkerOperationResponseSchema, } from "./worker-operation.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/agent/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,+BAA+B,EAC/B,2BAA2B,EAC3B,KAAK,eAAe,EACpB,KAAK,wBAAwB,EAC7B,8BAA8B,EAC9B,qBAAqB,EACrB,KAAK,uBAAuB,EAC5B,6BAA6B,EAC7B,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,wBAAwB,EAC7B,8BAA8B,GAC/B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,KAAK,2BAA2B,EAChC,iCAAiC,EACjC,KAAK,4BAA4B,EACjC,kCAAkC,GACnC,MAAM,uBAAuB,CAAC"}

package/dist/agent/index.js

@@ -0,0 +1,4 @@
+export { AGENT_DEFINITION_SCHEMA_VERSION, AGENT_REQUEST_OPERATION_IDS, agentDefinitionReferenceSchema, agentDefinitionSchema, agentDefinitionSnapshotSchema, encodeAgentDefinition, LOCAL_NODE_METHOD_EXPOSURE, } from "./definition.js";
+export { agentPermissionPreflightSchema, } from "./permission-preflight.js";
+export { agentWorkerOperationRequestSchema, agentWorkerOperationResponseSchema, } from "./worker-operation.js";
+//# sourceMappingURL=index.js.map

package/dist/agent/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,+BAA+B,EAC/B,2BAA2B,EAG3B,8BAA8B,EAC9B,qBAAqB,EAErB,6BAA6B,EAC7B,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAEL,8BAA8B,GAC/B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAEL,iCAAiC,EAEjC,kCAAkC,GACnC,MAAM,uBAAuB,CAAC"}

package/dist/agent/permission-preflight.d.ts

@@ -0,0 +1,18 @@
+import type { InferRuntimeSchema } from "../runtime-schema/index.js";
+export declare const agentPermissionPreflightSchema: import("../runtime-schema/runtime-schema.js").RuntimeSchema<{
+    readonly definitionRef: {
+        readonly contentDigest: string;
+        readonly key: string;
+        readonly version: string;
+    };
+    readonly grantedOperationIds: readonly never[];
+    readonly reason: "explicit_agent_grant_unavailable";
+    readonly schemaVersion: "maia.agent-permission-preflight/v1";
+    readonly sessionId: string;
+    readonly sessionRevision: string;
+    readonly status: "denied";
+    readonly workspaceId: string;
+    readonly workspaceRevision: string;
+}>;
+export type AgentPermissionPreflight = InferRuntimeSchema<typeof agentPermissionPreflightSchema>;
+//# sourceMappingURL=permission-preflight.d.ts.map

package/dist/agent/permission-preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-preflight.d.ts","sourceRoot":"","sources":["../../src/agent/permission-preflight.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAMrE,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;EAY1C,CAAC;AACF,MAAM,MAAM,wBAAwB,GAAG,kBAAkB,CACvD,OAAO,8BAA8B,CACtC,CAAC"}

package/dist/agent/permission-preflight.js

@@ -0,0 +1,18 @@
+import * as Schema from "effect/Schema";
+import { aggregateRevisionEffectSchema, protocolIdentifierEffectSchema, } from "../envelope/effect-schema.js";
+import { makeEffectRuntimeSchema } from "../runtime-schema/effect-schema.js";
+import { agentDefinitionReferenceEffectSchema } from "./effect-schema.js";
+// Denial evidence, not a grant or an input accepted by a public operation.
+// A positive variant requires Node-owned issuance and a reviewed worker adapter.
+export const agentPermissionPreflightSchema = makeEffectRuntimeSchema(Schema.Struct({
+    definitionRef: agentDefinitionReferenceEffectSchema,
+    grantedOperationIds: Schema.Array(Schema.Never),
+    reason: Schema.Literal("explicit_agent_grant_unavailable"),
+    schemaVersion: Schema.Literal("maia.agent-permission-preflight/v1"),
+    sessionId: protocolIdentifierEffectSchema,
+    sessionRevision: aggregateRevisionEffectSchema,
+    status: Schema.Literal("denied"),
+    workspaceId: protocolIdentifierEffectSchema,
+    workspaceRevision: aggregateRevisionEffectSchema,
+}));
+//# sourceMappingURL=permission-preflight.js.map

package/dist/agent/permission-preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-preflight.js","sourceRoot":"","sources":["../../src/agent/permission-preflight.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,EACL,6BAA6B,EAC7B,8BAA8B,GAC/B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,uBAAuB,EAAE,MAAM,oCAAoC,CAAC;AAG7E,OAAO,EAAE,oCAAoC,EAAE,MAAM,oBAAoB,CAAC;AAE1E,2EAA2E;AAC3E,iFAAiF;AACjF,MAAM,CAAC,MAAM,8BAA8B,GAAG,uBAAuB,CACnE,MAAM,CAAC,MAAM,CAAC;IACZ,aAAa,EAAE,oCAAoC;IACnD,mBAAmB,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC;IAC/C,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,kCAAkC,CAAC;IAC1D,aAAa,EAAE,MAAM,CAAC,OAAO,CAAC,oCAAoC,CAAC;IACnE,SAAS,EAAE,8BAA8B;IACzC,eAAe,EAAE,6BAA6B;IAC9C,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC;IAChC,WAAW,EAAE,8BAA8B;IAC3C,iBAAiB,EAAE,6BAA6B;CACjD,CAAC,CACH,CAAC"}

package/dist/agent/worker-operation.d.ts

@@ -0,0 +1,53 @@
+import type { InferRuntimeSchema } from "../runtime-schema/index.js";
+export declare const agentWorkerOperationRequestSchema: import("../runtime-schema/runtime-schema.js").RuntimeSchema<{
+    readonly method: "session.show";
+    readonly requestId: string;
+    readonly schemaVersion: "maia.agent-worker-operation/v1";
+}>;
+export type AgentWorkerOperationRequest = InferRuntimeSchema<typeof agentWorkerOperationRequestSchema>;
+export declare const agentWorkerOperationResponseSchema: import("../runtime-schema/runtime-schema.js").RuntimeSchema<{
+    readonly requestId: string;
+    readonly result: {
+        readonly method: "session.show";
+        readonly session: {
+            readonly createdAt: string;
+            readonly id: string;
+            readonly projectId: string;
+            readonly revision: string;
+            readonly state: "failed" | "idle" | "interrupted" | "recovering" | "running" | "starting" | "stopped" | "stopping" | "waiting-approval";
+            readonly updatedAt: string;
+            readonly workspaceId: string;
+            readonly workspaceRevision: string;
+            readonly agentDefinitionRef?: {
+                readonly contentDigest: string;
+                readonly key: string;
+                readonly version: string;
+            } | undefined;
+            readonly executor?: {
+                readonly connectionId: string;
+                readonly kind: "claude-code" | "codex-cli";
+                readonly model?: string | undefined;
+            } | undefined;
+            readonly failure?: {
+                readonly code: string;
+                readonly message: string;
+            } | undefined;
+            readonly schemaVersion: 4;
+            readonly title?: string | undefined;
+            readonly worktree?: {
+                readonly baseRef: string;
+                readonly baseRevision: string;
+                readonly branch: string;
+                readonly setup: "failed" | "none" | "pending" | "succeeded";
+                readonly skills?: readonly {
+                    readonly digest: string;
+                    readonly name: string;
+                }[] | undefined;
+                readonly state: "active" | "archived" | "removed";
+            } | undefined;
+        };
+    };
+    readonly schemaVersion: "maia.agent-worker-operation/v1";
+}>;
+export type AgentWorkerOperationResponse = InferRuntimeSchema<typeof agentWorkerOperationResponseSchema>;
+//# sourceMappingURL=worker-operation.d.ts.map

package/dist/agent/worker-operation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-operation.d.ts","sourceRoot":"","sources":["../../src/agent/worker-operation.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAKrE,eAAO,MAAM,iCAAiC;;;;EAM7C,CAAC;AACF,MAAM,MAAM,2BAA2B,GAAG,kBAAkB,CAC1D,OAAO,iCAAiC,CACzC,CAAC;AACF,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAW9C,CAAC;AACF,MAAM,MAAM,4BAA4B,GAAG,kBAAkB,CAC3D,OAAO,kCAAkC,CAC1C,CAAC"}

package/dist/agent/worker-operation.js

@@ -0,0 +1,17 @@
+import * as Schema from "effect/Schema";
+import { protocolIdentifierEffectSchema } from "../envelope/effect-schema.js";
+import { makeEffectRuntimeSchema } from "../runtime-schema/effect-schema.js";
+import { sessionShowResultEffectSchema } from "../session/effect-schema.js";
+// Private worker receiver candidate: identity and target come from its owner,
+// never from a model-authored request. Reject generic operation envelopes.
+export const agentWorkerOperationRequestSchema = makeEffectRuntimeSchema(Schema.Struct({
+    method: Schema.Literal("session.show"),
+    requestId: protocolIdentifierEffectSchema,
+    schemaVersion: Schema.Literal("maia.agent-worker-operation/v1"),
+}));
+export const agentWorkerOperationResponseSchema = makeEffectRuntimeSchema(Schema.Struct({
+    requestId: protocolIdentifierEffectSchema,
+    result: sessionShowResultEffectSchema,
+    schemaVersion: Schema.Literal("maia.agent-worker-operation/v1"),
+}).check(Schema.makeFilter((value) => new TextEncoder().encode(JSON.stringify(value)).byteLength <= 65_536)));
+//# sourceMappingURL=worker-operation.js.map

package/dist/agent/worker-operation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-operation.js","sourceRoot":"","sources":["../../src/agent/worker-operation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,EAAE,8BAA8B,EAAE,MAAM,8BAA8B,CAAC;AAC9E,OAAO,EAAE,uBAAuB,EAAE,MAAM,oCAAoC,CAAC;AAE7E,OAAO,EAAE,6BAA6B,EAAE,MAAM,6BAA6B,CAAC;AAE5E,8EAA8E;AAC9E,2EAA2E;AAC3E,MAAM,CAAC,MAAM,iCAAiC,GAAG,uBAAuB,CACtE,MAAM,CAAC,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC;IACtC,SAAS,EAAE,8BAA8B;IACzC,aAAa,EAAE,MAAM,CAAC,OAAO,CAAC,gCAAgC,CAAC;CAChE,CAAC,CACH,CAAC;AAIF,MAAM,CAAC,MAAM,kCAAkC,GAAG,uBAAuB,CACvE,MAAM,CAAC,MAAM,CAAC;IACZ,SAAS,EAAE,8BAA8B;IACzC,MAAM,EAAE,6BAA6B;IACrC,aAAa,EAAE,MAAM,CAAC,OAAO,CAAC,gCAAgC,CAAC;CAChE,CAAC,CAAC,KAAK,CACN,MAAM,CAAC,UAAU,CACf,CAAC,KAAK,EAAE,EAAE,CACR,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,IAAI,MAAM,CACvE,CACF,CACF,CAAC"}