macp-sdk-typescript 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -4,15 +4,138 @@ All notable changes to `macp-sdk-typescript` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 project uses [Semantic Versioning](https://semver.org/).
 
-## [Unreleased]
+## [0.3.0] - 2026-04-21
+
+Parity release — brings TypeScript SDK to full feature parity with
+`macp-sdk-python` 0.3.0. Plan: `plans/sdk-parity-plan.md`.
+
+### Added
+
+- **Cancel-callback server** (Gap B, RFC-0001 §7.2 Option A):
+  `startCancelCallbackServer({ host, port, path, onCancel })` returns a
+  handle backed by Node's `http` module; `Participant` starts the server
+  automatically when `ParticipantConfig.cancelCallback` is set and closes
+  it on `stop()`. `fromBootstrap()` wires the new `cancel_callback`
+  field in the bootstrap JSON. Exports:
+  `startCancelCallbackServer`, `CancelCallbackServer`, `CancelHandler`.
+- **Function-wrapped voting and commitment strategies** (Gap C):
+  `functionVoter(shouldVote, decideVote)` and
+  `functionCommitter(shouldCommit, decideCommitment)` in
+  `src/agent/strategies.ts` — the low-friction way to plug a custom rule
+  into a `Participant` without a class.
+- **Standalone signal and progress builders** (Gap D):
+  `buildSignalPayload(input)` and `buildProgressPayload(input)` in
+  `src/envelope.ts`. `MacpClient.sendSignal` / `sendProgress` now use
+  the shared builders internally.
+- **`serializeMessage(msg)` helper** (Gap N) — parity with
+  `python-sdk envelope.serialize_message`; dispatches to
+  `serializeBinary()` / `toBinary()` / `finish()` on the passed
+  protobuf message.
+- **Structured logger** (Gap G): `src/logging.ts` exports `logger` with
+  `error`/`warn`/`info`/`debug` level methods and `configureLogging({ level, sink })`.
+  Reads `MACP_LOG_LEVEL` on module init (default `warn`). The two
+  remaining `console.*` callsites in `src/agent/participant.ts` and
+  `src/handoff.ts` now route through the structured logger.
+- **`AckFailure` shape** (Gap I): structured NACK record exported from
+  `src/errors.ts`. Populated on `MacpAckError.failure` from both
+  `ack.error.details` and gRPC trailing metadata.
+- **`BaseSession` / `BaseProjection`** (Gap J): abstract extension
+  points exported from `src/base-session.ts` and `src/projections/base.ts`
+  for custom mode helpers (modes registered via `registerExtMode`).
+  Mirrors `python-sdk`'s `BaseSession` / `BaseProjection`.
+- **Named policy rule interfaces** (Gap K): `VotingRules`,
+  `ObjectionHandlingRules`, `EvaluationRules`, `CommitmentRules`,
+  `QuorumThreshold`, `AbstentionRules`, `ProposalAcceptanceRules`,
+  `CounterProposalRules`, `RejectionRules`, `TaskAssignmentRules`,
+  `TaskCompletionRules`, `HandoffAcceptanceRules` now exported as
+  first-class interfaces matching `macp-sdk-python` exports.
+- **`STANDARD_MODES` tuple** (Gap L) in `src/constants.ts`.
+- **Parity examples** (Gap M): `examples/policy-registration.ts`,
+  `examples/agent-policy-aware.ts`, `examples/direct-agent-auth-initiator.ts`,
+  `examples/direct-agent-auth-observer.ts`.
+
+### Changed
+
+- **Error-code constants renamed** (Gap F, breaking): dropped the
+  `ERR_` prefix so TS constants match the on-the-wire strings and the
+  `macp-sdk-python` exports. Rename table —
+  `ERR_UNSUPPORTED_PROTOCOL_VERSION` → `UNSUPPORTED_PROTOCOL_VERSION`,
+  `ERR_INVALID_ENVELOPE` → `INVALID_ENVELOPE`,
+  `ERR_SESSION_NOT_FOUND` → `SESSION_NOT_FOUND`,
+  `ERR_SESSION_NOT_OPEN` → `SESSION_NOT_OPEN`,
+  `ERR_SESSION_ALREADY_EXISTS` → `SESSION_ALREADY_EXISTS`,
+  `ERR_MODE_NOT_SUPPORTED` → `MODE_NOT_SUPPORTED`,
+  `ERR_FORBIDDEN` → `FORBIDDEN`,
+  `ERR_UNAUTHENTICATED` → `UNAUTHENTICATED`,
+  `ERR_DUPLICATE_MESSAGE` → `DUPLICATE_MESSAGE`,
+  `ERR_PAYLOAD_TOO_LARGE` → `PAYLOAD_TOO_LARGE`,
+  `ERR_RATE_LIMITED` → `RATE_LIMITED`,
+  `ERR_INTERNAL_ERROR` → `INTERNAL_ERROR`,
+  `ERR_POLICY_DENIED` → `POLICY_DENIED`,
+  `ERR_INVALID_SESSION_ID` → `INVALID_SESSION_ID`,
+  `ERR_UNKNOWN_POLICY_VERSION` → `UNKNOWN_POLICY_VERSION`,
+  `ERR_INVALID_POLICY_DEFINITION` → `INVALID_POLICY_DEFINITION`.
+- `MacpClient.clientVersion` default now `0.3.0`.
+
+### Removed
+
+- **`HandoffSession.sendContext()`** (Gap A, breaking): the deprecated
+  alias (warning first emitted in 0.2.3) has been removed. Use
+  `HandoffSession.addContext()`.
+- **`MacpAckError.reasons` getter** (breaking): use
+  `MacpAckError.failure.reasons` instead. `.failure` is the canonical
+  structured NACK record and matches `macp-sdk-python`'s
+  `MacpAckError.failure`.
+- **Mode-prefixed policy rule type aliases** (breaking): the
+  `CommitmentRulesInput`, `DecisionVotingRules`,
+  `DecisionObjectionHandling`, `DecisionEvaluationRules`, and
+  `DecisionCommitmentRules` type aliases have been removed. Use the
+  unprefixed names (`CommitmentRules`, `VotingRules`,
+  `ObjectionHandlingRules`, `EvaluationRules`) introduced in Gap K.
+
+## [0.2.3] - 2026-04-21
 
 ### Added
+- `MacpStream.sendSubscribe(sessionId, afterSequence?)` — subscribe-only stream
+  frame (RFC-MACP-0006-A1). The runtime replays accepted envelopes from the
+  cursor before switching to live broadcast, so non-initiator agents observe
+  `SessionStart` and earlier mode envelopes regardless of join order.
+- `GrpcTransportAdapter` now sends a subscribe frame automatically on start so
+  `Participant`-based agents pick up history without bespoke wiring.
+- Unit coverage for `MacpStream.sendSubscribe` (default cursor, custom cursor,
+  closed-stream rejection, write-error propagation, sequential resubscribe) and
+  `GrpcTransportAdapter` (subscribe ordering, empty-stream subscribe, auth
+  pass-through to `openStream`).
+- Integration tests for late-subscriber replay and future-cursor skip
+  (`tests/integration/runtime.test.ts`).
+- `InitiatorConfig.sessionStart` now accepts `contextId` and `extensions`, and
+  `Participant.emitInitiatorEnvelopes()` forwards both to the mode-session
+  `start()` call (SDK-TS-1). `fromBootstrap()` decodes `context_id` plus a
+  JSON-native `extensions` map from the bootstrap file — each value is
+  serialised as UTF-8 JSON into the `Record<string, Buffer>` shape the
+  envelope requires; pre-encoded `Buffer` / `Uint8Array` values pass through
+  unchanged.
+- Documented `MacpClient.listSessions()` (parity with the python-sdk SDK-PY-2
+  gap) and `SessionLifecycleWatcher` (parity with python-sdk SDK-PY-3). Both
+  were already implemented — this release adds the API reference, a
+  `docs/guides/streaming.md` section, unit coverage for `listSessions`, and
+  integration tests that exercise enumeration + a `CREATED` lifecycle event
+  round-trip against a live runtime.
 - Warn-once migration hint when the deprecated `HandoffSession.sendContext()`
   alias is invoked. Scheduled for removal in `0.4.0`; use `addContext()`.
 - `docs/api/sessions.md` now documents the identity-guard contract.
 - `docs/guides/architecture.md` rewritten to reflect the three-layer design
   (transport / session helpers / agent framework).
 
+### Changed
+- Integration tests updated to match the proto field renames that landed in
+  `@multiagentcoordinationprotocol/proto@0.1.x`: `Evaluation.analysis` →
+  `reason`, `Proposal.description` → `summary`, `TaskRequest.assignee` →
+  `requestedAssignee` (Task accept/update/complete/fail/reject now carry an
+  `assignee` field), `TaskUpdate.progress` is required, `HandoffContext.data`
+  → `context` (+ `contentType`), `HandoffAccept.acceptedBy` and
+  `HandoffDecline.declinedBy` are now required.
+
 ### Deprecated
 - `HandoffSession.sendContext()` remains available as an alias but emits a
   one-shot `console.warn`. Use `HandoffSession.addContext()` instead.

package/README.md

@@ -74,6 +74,21 @@ Every session class follows the same pattern:
 4. Call `commit()` to finalize
 5. Read `session.projection` for local state
 
+### Session Start Options
+
+All `start()` methods accept `contextId` and `extensions` for session-level metadata:
+
+```typescript
+await session.start({
+  intent: 'pick a deployment strategy',
+  participants: ['alice', 'bob'],
+  ttlMs: 60_000,
+  contextId: 'ctx-abc',                           // optional opaque context reference
+  extensions: { 'x-trace': Buffer.from('tid') },  // optional typed extension buffers
+  roots: [{ uri: 'file:///workspace', name: 'repo' }],
+});
+```
+
 ## Coordination Modes
 
 ### Decision Mode
@@ -126,10 +141,10 @@ import { TaskSession } from 'macp-sdk-typescript';
 
 const session = new TaskSession(client);
 await session.start({ intent: '...', participants: ['worker'], ttlMs: 120_000 });
-await session.request({ taskId: 't1', title: 'Build feature', instructions: '...' });
+await session.requestTask({ taskId: 't1', title: 'Build feature', instructions: '...' });
 await session.acceptTask({ taskId: 't1', assignee: 'worker' });
-await session.update({ taskId: 't1', status: 'working', progress: 0.5, message: 'halfway' });
-await session.complete({ taskId: 't1', assignee: 'worker', summary: 'done' });
+await session.updateTask({ taskId: 't1', status: 'working', progress: 0.5, message: 'halfway' });
+await session.completeTask({ taskId: 't1', assignee: 'worker', summary: 'done' });
 await session.commit({ action: 'task.completed', authorityScope: 'lead', reason: '...' });
 
 // Projection queries
@@ -177,6 +192,76 @@ session.projection.remainingVotesNeeded('r1');   // number
 session.projection.votedSenders('r1');           // string[]
 ```
 
+## Agent Framework
+
+The `agent` module provides event-driven abstractions for building MACP participants.
+
+### Participant
+
+`Participant` wraps a session, projection, and transport into a single event-driven handler:
+
+```typescript
+import { agent } from 'macp-sdk-typescript';
+
+const participant = new agent.Participant({
+  participantId: 'evaluator',
+  sessionId: 'sid-123',
+  mode: 'macp.mode.decision.v1',
+  client,
+  transport: new agent.GrpcTransportAdapter(client, 'sid-123', auth),
+});
+
+participant
+  .on('Proposal', async (msg, ctx) => {
+    await ctx.actions.evaluate({
+      proposalId: msg.payload.proposalId,
+      recommendation: 'APPROVE',
+      confidence: 0.95,
+    });
+  })
+  .onTerminal(async (result) => {
+    console.log('session ended:', result.reason);
+  });
+
+await participant.run();
+```
+
+### Bootstrap Runner
+
+`fromBootstrap()` creates a fully-wired `Participant` from a JSON bootstrap file (typically provided by the runtime orchestrator):
+
+```typescript
+import { agent } from 'macp-sdk-typescript';
+
+// Reads from path argument or MACP_BOOTSTRAP_FILE env var
+const participant = agent.fromBootstrap('./bootstrap.json');
+participant.on('Proposal', handler);
+await participant.run();
+```
+
+Bootstrap files can include an `initiator` section for participants that start the session:
+
+```json
+{
+  "session_id": "sid-123",
+  "participant_id": "coordinator",
+  "mode": "macp.mode.decision.v1",
+  "runtime_address": "localhost:50051",
+  "initiator": {
+    "session_start": {
+      "intent": "pick deployment strategy",
+      "participants": ["coordinator", "evaluator"],
+      "ttl_ms": 60000,
+      "roots": [{ "uri": "file:///workspace" }]
+    },
+    "kickoff": {
+      "message_type": "Proposal",
+      "payload": { "proposalId": "p1", "option": "canary" }
+    }
+  }
+}
+```
+
 ## Authentication
 
 ```typescript
@@ -234,6 +319,17 @@ for await (const envelope of stream.responses()) {
 stream.close();
 ```
 
+To attach to a session that is already in flight and receive accepted history before live broadcast (RFC-MACP-0006 §3.2 passive subscribe):
+
+```typescript
+const stream = client.openStream({ auth });
+await stream.sendSubscribe(sessionId);            // full replay then live
+// or, after a reconnect:
+await stream.sendSubscribe(sessionId, lastSeq);    // resume from cursor
+```
+
+The agent framework's `GrpcTransportAdapter` calls this for you on start, so non-initiator agents see `SessionStart` regardless of join order.
+
 ### Registry & Root Watchers
 
 ```typescript

package/dist/agent/cancel-callback.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Cancel-callback HTTP endpoint — RFC-0001 §7.2 Option A.
+ *
+ * Parity with python-sdk's `macp_sdk.agent.cancel_callback`. The
+ * examples-service's `BootstrapPayload.cancel_callback` field asks each
+ * agent to listen on `http://host:port{path}` for a `POST` whose JSON
+ * body is `{"runId": ..., "reason": ...}`. Receipt of the POST should
+ * stop the participant cleanly — typically by calling `participant.stop()`.
+ */
+export type CancelHandler = (runId: string, reason: string) => void | Promise<void>;
+export interface CancelCallbackServerOptions {
+    host: string;
+    port: number;
+    path: string;
+    onCancel: CancelHandler;
+}
+export interface CancelCallbackServer {
+    readonly host: string;
+    readonly port: number;
+    readonly path: string;
+    close(): Promise<void>;
+}
+export declare function startCancelCallbackServer(options: CancelCallbackServerOptions): Promise<CancelCallbackServer>;

package/dist/agent/cancel-callback.js

@@ -0,0 +1,108 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startCancelCallbackServer = startCancelCallbackServer;
+const http = __importStar(require("node:http"));
+const logging_1 = require("../logging");
+function normalisePath(path) {
+    return path.startsWith('/') ? path : `/${path}`;
+}
+async function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on('data', (chunk) => chunks.push(chunk));
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+        req.on('error', reject);
+    });
+}
+function startCancelCallbackServer(options) {
+    const path = normalisePath(options.path);
+    return new Promise((resolve, reject) => {
+        const server = http.createServer(async (req, res) => {
+            if (req.method !== 'POST' || req.url !== path) {
+                res.statusCode = 404;
+                res.end();
+                return;
+            }
+            let body = {};
+            try {
+                const raw = await readBody(req);
+                if (raw)
+                    body = JSON.parse(raw);
+            }
+            catch {
+                body = {};
+            }
+            const runId = String(body.runId ?? body.run_id ?? '');
+            const reason = String(body.reason ?? '');
+            logging_1.logger.info('cancel_callback invoked', { runId, reason });
+            try {
+                await options.onCancel(runId, reason);
+            }
+            catch (err) {
+                logging_1.logger.error('cancel_callback handler raised', err);
+                res.statusCode = 500;
+                res.end();
+                return;
+            }
+            res.statusCode = 202;
+            res.setHeader('Content-Type', 'application/json');
+            res.end('{"ok":true}');
+        });
+        server.once('error', reject);
+        server.listen(options.port, options.host, () => {
+            server.removeListener('error', reject);
+            const addr = server.address();
+            const boundHost = addr.address;
+            const boundPort = addr.port;
+            logging_1.logger.debug(`cancel_callback listening on http://${boundHost}:${boundPort}${path}`);
+            let closing = false;
+            const handle = {
+                host: boundHost,
+                port: boundPort,
+                path,
+                close() {
+                    if (closing)
+                        return Promise.resolve();
+                    closing = true;
+                    return new Promise((res, rej) => {
+                        server.close((err) => (err ? rej(err) : res()));
+                    });
+                },
+            };
+            resolve(handle);
+        });
+    });
+}

package/dist/agent/index.d.ts

@@ -1,4 +1,5 @@
 export * from './types';
+export * from './cancel-callback';
 export * from './dispatcher';
 export * from './participant';
 export * from './strategies';

package/dist/agent/index.js

@@ -16,6 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpTransportAdapter = exports.GrpcTransportAdapter = void 0;
 __exportStar(require("./types"), exports);
+__exportStar(require("./cancel-callback"), exports);
 __exportStar(require("./dispatcher"), exports);
 __exportStar(require("./participant"), exports);
 __exportStar(require("./strategies"), exports);

package/dist/agent/participant.d.ts

@@ -1,7 +1,27 @@
 import type { AuthConfig } from '../auth';
 import type { MacpClient } from '../client';
+import type { Envelope } from '../types';
+import { type CancelCallbackServer } from './cancel-callback';
 import { type TransportAdapter } from './transports';
 import type { MessageHandler, PhaseChangeHandler, ProjectionLike, SessionActions, TerminalHandler } from './types';
+export interface InitiatorConfig {
+    sessionStart: {
+        intent: string;
+        participants: string[];
+        ttlMs: number;
+        contextId?: string;
+        extensions?: Record<string, Buffer>;
+        context?: Record<string, unknown>;
+        roots?: Array<{
+            uri: string;
+            name?: string;
+        }>;
+    };
+    kickoff?: {
+        messageType: string;
+        payload: Record<string, unknown>;
+    };
+}
 export interface ParticipantConfig {
     participantId: string;
     sessionId: string;
@@ -13,6 +33,18 @@ export interface ParticipantConfig {
     configurationVersion?: string;
     policyVersion?: string;
     transport?: TransportAdapter;
+    initiator?: InitiatorConfig;
+    /**
+     * Bind a cancel-callback HTTP endpoint (RFC-0001 §7.2 Option A) when
+     * this participant's event loop starts. The server is closed
+     * automatically when {@link Participant.stop} is called. Parity with
+     * python-sdk's bootstrap `cancel_callback` field.
+     */
+    cancelCallback?: {
+        host: string;
+        port: number;
+        path: string;
+    };
 }
 export declare class Participant {
     readonly participantId: string;
@@ -25,14 +57,40 @@ export declare class Participant {
     private readonly dispatcher;
     private readonly session;
     private readonly transport;
+    private readonly initiatorConfig?;
+    private readonly participants;
+    private readonly modeVersion?;
+    private readonly configurationVersion?;
+    private readonly policyVersion?;
     private running;
     private lastPhase;
+    private cancelCallbackServer?;
+    private readonly cancelCallbackConfig?;
     constructor(config: ParticipantConfig);
     private createModeSession;
     private buildActions;
     on(messageType: string, handler: MessageHandler): Participant;
     onPhaseChange(phase: string, handler: PhaseChangeHandler): Participant;
     onTerminal(handler: TerminalHandler): Participant;
+    /** Whether {@link stop} has been called (or the loop has exited). */
+    get isStopped(): boolean;
     run(): Promise<void>;
+    /**
+     * Manually process a single envelope. Parity with python-sdk's
+     * {@code Participant.process_event}. Useful for deterministic unit tests
+     * and for driving the participant from a foreign event loop without
+     * installing a {@link TransportAdapter}.
+     */
+    processEvent(envelope: Envelope): Promise<void>;
+    private buildHandlerContext;
+    /** Returns true if a terminal state was reached. */
+    private processMessage;
     stop(): Promise<void>;
+    /**
+     * Attach a running cancel-callback HTTP server to this participant.
+     * The server is closed automatically when {@link stop} is called.
+     * Parity with python-sdk's `Participant.attach_cancel_callback_server`.
+     */
+    attachCancelCallbackServer(server: CancelCallbackServer): void;
+    private emitInitiatorEnvelopes;
 }