macp-sdk-typescript 0.2.0 → 0.2.2

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
@@ -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

package/dist/agent/participant.d.ts

@@ -2,6 +2,22 @@ import type { AuthConfig } from '../auth';
 import type { MacpClient } from '../client';
 import { type TransportAdapter } from './transports';
 import type { MessageHandler, PhaseChangeHandler, ProjectionLike, SessionActions, TerminalHandler } from './types';
+export interface InitiatorConfig {
+    sessionStart: {
+        intent: string;
+        participants: string[];
+        ttlMs: number;
+        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 +29,7 @@ export interface ParticipantConfig {
     configurationVersion?: string;
     policyVersion?: string;
     transport?: TransportAdapter;
+    initiator?: InitiatorConfig;
 }
 export declare class Participant {
     readonly participantId: string;
@@ -25,6 +42,7 @@ export declare class Participant {
     private readonly dispatcher;
     private readonly session;
     private readonly transport;
+    private readonly initiatorConfig?;
     private running;
     private lastPhase;
     constructor(config: ParticipantConfig);
@@ -35,4 +53,5 @@ export declare class Participant {
     onTerminal(handler: TerminalHandler): Participant;
     run(): Promise<void>;
     stop(): Promise<void>;
+    private emitInitiatorEnvelopes;
 }

package/dist/agent/participant.js

@@ -21,6 +21,7 @@ class Participant {
     dispatcher;
     session;
     transport;
+    initiatorConfig;
     running = false;
     lastPhase;
     constructor(config) {
@@ -43,6 +44,7 @@ class Participant {
         this.lastPhase = projection.phase;
         this.actions = this.buildActions();
         this.transport = config.transport ?? new transports_1.GrpcTransportAdapter(config.client, config.sessionId, config.auth);
+        this.initiatorConfig = config.initiator;
     }
     createModeSession(mode, client, opts) {
         switch (mode) {
@@ -158,6 +160,9 @@ class Participant {
         if (this.running)
             return;
         this.running = true;
+        if (this.initiatorConfig && this.session) {
+            await this.emitInitiatorEnvelopes();
+        }
         const sessionInfo = {
             sessionId: this.sessionId,
             mode: this.mode,
@@ -217,5 +222,29 @@ class Participant {
         this.running = false;
         await this.transport.stop();
     }
+    async emitInitiatorEnvelopes() {
+        if (!this.initiatorConfig || !this.session)
+            return;
+        const ss = this.initiatorConfig.sessionStart;
+        if ('start' in this.session && typeof this.session.start === 'function') {
+            await this.session.start({
+                intent: ss.intent,
+                participants: ss.participants,
+                ttlMs: ss.ttlMs,
+                roots: ss.roots,
+            });
+        }
+        const kickoff = this.initiatorConfig.kickoff;
+        if (!kickoff)
+            return;
+        if (kickoff.messageType === 'Proposal' && this.session instanceof decision_1.DecisionSession) {
+            const payload = kickoff.payload;
+            await this.session.propose({
+                proposalId: String(payload.proposalId ?? payload.proposal_id ?? `${this.sessionId}-kickoff`),
+                option: String(payload.option ?? 'decide'),
+                rationale: payload.rationale !== undefined ? String(payload.rationale) : undefined,
+            });
+        }
+    }
 }
 exports.Participant = Participant;

package/dist/agent/runner.d.ts

@@ -11,8 +11,28 @@ export interface BootstrapPayload {
     auth_token?: string;
     agent_id?: string;
     secure?: boolean;
-    /** Mirror of {@link MacpClientOptions.allowInsecure}; required when `secure` is false. */
     allow_insecure?: boolean;
     participants?: string[];
+    initiator?: {
+        session_start: {
+            intent: string;
+            participants: string[];
+            ttl_ms: number;
+            mode_version?: string;
+            configuration_version?: string;
+            policy_version?: string;
+            context?: Record<string, unknown>;
+            roots?: Array<{
+                uri: string;
+                name?: string;
+            }>;
+        };
+        kickoff?: {
+            message_type: string;
+            payload_type?: string;
+            payload: Record<string, unknown>;
+        };
+    };
+    metadata?: Record<string, unknown>;
 }
 export declare function fromBootstrap(bootstrapPath?: string): Participant;

package/dist/agent/runner.js

@@ -69,6 +69,24 @@ function fromBootstrap(bootstrapPath) {
         allowInsecure: payload.allow_insecure,
         auth,
     });
+    let initiator;
+    if (payload.initiator) {
+        const ss = payload.initiator.session_start;
+        initiator = {
+            sessionStart: {
+                intent: ss.intent,
+                participants: ss.participants,
+                ttlMs: ss.ttl_ms,
+                roots: ss.roots,
+            },
+            kickoff: payload.initiator.kickoff
+                ? {
+                    messageType: payload.initiator.kickoff.message_type,
+                    payload: payload.initiator.kickoff.payload,
+                }
+                : undefined,
+        };
+    }
     const config = {
         participantId: payload.participant_id,
         sessionId: payload.session_id,
@@ -79,6 +97,7 @@ function fromBootstrap(bootstrapPath) {
         modeVersion: payload.mode_version,
         configurationVersion: payload.configuration_version,
         policyVersion: payload.policy_version ?? constants_1.DEFAULT_POLICY_VERSION,
+        initiator,
     };
     return new participant_1.Participant(config);
 }

package/dist/client.d.ts

@@ -125,6 +125,11 @@ export declare class MacpClient {
         auth?: AuthConfig;
         deadlineMs?: number;
     }): Promise<PolicyDescriptor[]>;
+    listSessions(options?: {
+        auth?: AuthConfig;
+        deadlineMs?: number;
+    }): Promise<SessionMetadata[]>;
+    watchSessions(auth?: AuthConfig): grpc.ClientReadableStream<any>;
     watchPolicies(auth?: AuthConfig): grpc.ClientReadableStream<any>;
     /** @deprecated Use {@link watchPolicies}. Scheduled for removal in 0.4.0. */
     _watchPolicies(auth?: AuthConfig): grpc.ClientReadableStream<any>;

package/dist/client.js

@@ -214,7 +214,7 @@ class MacpClient {
                 websiteUrl: '',
             },
             capabilities: {
-                sessions: { stream: true },
+                sessions: { stream: true, listSessions: true, watchSessions: true },
                 cancellation: { cancelSession: true },
                 progress: { progress: true },
                 manifest: { getManifest: true },
@@ -293,6 +293,15 @@ class MacpClient {
         const res = await this.unary('ListPolicies', { mode: mode || '' }, auth, options?.deadlineMs);
         return res.descriptors || [];
     }
+    async listSessions(options) {
+        const auth = this.requireAuth(options?.auth);
+        const res = await this.unary('ListSessions', {}, auth, options?.deadlineMs);
+        return res.sessions || [];
+    }
+    watchSessions(auth) {
+        const metadata = this.metadata(auth);
+        return metadata ? this.client.WatchSessions({}, metadata) : this.client.WatchSessions({});
+    }
     watchPolicies(auth) {
         const metadata = this.metadata(auth);
         return metadata ? this.client.WatchPolicies({}, metadata) : this.client.WatchPolicies({});

package/dist/decision.d.ts

@@ -24,7 +24,8 @@ export declare class DecisionSession {
         intent: string;
         participants: string[];
         ttlMs: number;
-        context?: Buffer | string | Record<string, unknown>;
+        contextId?: string;
+        extensions?: Record<string, Buffer>;
         roots?: {
             uri: string;
             name?: string;

package/dist/decision.js

@@ -47,7 +47,8 @@ class DecisionSession {
             intent: input.intent,
             participants: input.participants,
             ttlMs: input.ttlMs,
-            context: input.context,
+            contextId: input.contextId,
+            extensions: input.extensions,
             roots: input.roots,
             modeVersion: this.modeVersion,
             configurationVersion: this.configurationVersion,

package/dist/envelope.d.ts

@@ -3,7 +3,6 @@ export declare function newSessionId(): string;
 export declare function newMessageId(): string;
 export declare function newCommitmentId(): string;
 export declare function nowUnixMs(): number;
-export declare function encodeContext(context?: Buffer | string | Record<string, unknown>): Buffer;
 export declare function buildSessionStartPayload(input: {
     intent: string;
     participants: string[];
@@ -11,7 +10,8 @@ export declare function buildSessionStartPayload(input: {
     modeVersion?: string;
     configurationVersion?: string;
     policyVersion?: string;
-    context?: Buffer | string | Record<string, unknown>;
+    contextId?: string;
+    extensions?: Record<string, Buffer>;
     roots?: Root[];
 }): SessionStartPayload;
 export declare function inferOutcomePositive(action: string): boolean;

package/dist/envelope.js

@@ -4,7 +4,6 @@ exports.newSessionId = newSessionId;
 exports.newMessageId = newMessageId;
 exports.newCommitmentId = newCommitmentId;
 exports.nowUnixMs = nowUnixMs;
-exports.encodeContext = encodeContext;
 exports.buildSessionStartPayload = buildSessionStartPayload;
 exports.inferOutcomePositive = inferOutcomePositive;
 exports.buildCommitmentPayload = buildCommitmentPayload;
@@ -25,15 +24,6 @@ function newCommitmentId() {
 function nowUnixMs() {
     return Date.now();
 }
-function encodeContext(context) {
-    if (!context)
-        return Buffer.alloc(0);
-    if (Buffer.isBuffer(context))
-        return context;
-    if (typeof context === 'string')
-        return Buffer.from(context, 'utf8');
-    return Buffer.from(JSON.stringify(context), 'utf8');
-}
 function buildSessionStartPayload(input) {
     return {
         intent: input.intent,
@@ -42,7 +32,8 @@ function buildSessionStartPayload(input) {
         configurationVersion: input.configurationVersion ?? constants_1.DEFAULT_CONFIGURATION_VERSION,
         policyVersion: input.policyVersion ?? constants_1.DEFAULT_POLICY_VERSION,
         ttlMs: input.ttlMs,
-        context: encodeContext(input.context),
+        contextId: input.contextId ?? '',
+        extensions: input.extensions ?? {},
         roots: input.roots ?? [],
     };
 }

package/dist/handoff.d.ts

@@ -24,7 +24,8 @@ export declare class HandoffSession {
         intent: string;
         participants: string[];
         ttlMs: number;
-        context?: Buffer | string | Record<string, unknown>;
+        contextId?: string;
+        extensions?: Record<string, Buffer>;
         roots?: {
             uri: string;
             name?: string;

package/dist/handoff.js

@@ -55,7 +55,8 @@ class HandoffSession {
             intent: input.intent,
             participants: input.participants,
             ttlMs: input.ttlMs,
-            context: input.context,
+            contextId: input.contextId,
+            extensions: input.extensions,
             roots: input.roots,
             modeVersion: this.modeVersion,
             configurationVersion: this.configurationVersion,

package/dist/policy.js

@@ -38,7 +38,7 @@ function buildDecisionPolicy(policyId, description, rules) {
         policyId,
         mode: 'macp.mode.decision.v1',
         description,
-        rules: Buffer.from(JSON.stringify(rulesJson)),
+        rules: JSON.stringify(rulesJson),
         schemaVersion: 1,
     };
 }
@@ -58,7 +58,7 @@ function buildQuorumPolicy(policyId, description, rules) {
         policyId,
         mode: 'macp.mode.quorum.v1',
         description,
-        rules: Buffer.from(JSON.stringify(rulesJson)),
+        rules: JSON.stringify(rulesJson),
         schemaVersion: 1,
     };
 }
@@ -79,7 +79,7 @@ function buildProposalPolicy(policyId, description, rules) {
         policyId,
         mode: 'macp.mode.proposal.v1',
         description,
-        rules: Buffer.from(JSON.stringify(rulesJson)),
+        rules: JSON.stringify(rulesJson),
         schemaVersion: 1,
     };
 }
@@ -97,7 +97,7 @@ function buildTaskPolicy(policyId, description, rules) {
         policyId,
         mode: 'macp.mode.task.v1',
         description,
-        rules: Buffer.from(JSON.stringify(rulesJson)),
+        rules: JSON.stringify(rulesJson),
         schemaVersion: 1,
     };
 }
@@ -112,7 +112,7 @@ function buildHandoffPolicy(policyId, description, rules) {
         policyId,
         mode: 'macp.mode.handoff.v1',
         description,
-        rules: Buffer.from(JSON.stringify(rulesJson)),
+        rules: JSON.stringify(rulesJson),
         schemaVersion: 1,
     };
 }

package/dist/proposal.d.ts

@@ -24,7 +24,8 @@ export declare class ProposalSession {
         intent: string;
         participants: string[];
         ttlMs: number;
-        context?: Buffer | string | Record<string, unknown>;
+        contextId?: string;
+        extensions?: Record<string, Buffer>;
         roots?: {
             uri: string;
             name?: string;

package/dist/proposal.js

@@ -47,7 +47,8 @@ class ProposalSession {
             intent: input.intent,
             participants: input.participants,
             ttlMs: input.ttlMs,
-            context: input.context,
+            contextId: input.contextId,
+            extensions: input.extensions,
             roots: input.roots,
             modeVersion: this.modeVersion,
             configurationVersion: this.configurationVersion,

package/dist/quorum.d.ts

@@ -24,7 +24,8 @@ export declare class QuorumSession {
         intent: string;
         participants: string[];
         ttlMs: number;
-        context?: Buffer | string | Record<string, unknown>;
+        contextId?: string;
+        extensions?: Record<string, Buffer>;
         roots?: {
             uri: string;
             name?: string;

package/dist/quorum.js

@@ -47,7 +47,8 @@ class QuorumSession {
             intent: input.intent,
             participants: input.participants,
             ttlMs: input.ttlMs,
-            context: input.context,
+            contextId: input.contextId,
+            extensions: input.extensions,
             roots: input.roots,
             modeVersion: this.modeVersion,
             configurationVersion: this.configurationVersion,

package/dist/task.d.ts

@@ -24,7 +24,8 @@ export declare class TaskSession {
         intent: string;
         participants: string[];
         ttlMs: number;
-        context?: Buffer | string | Record<string, unknown>;
+        contextId?: string;
+        extensions?: Record<string, Buffer>;
         roots?: {
             uri: string;
             name?: string;

package/dist/task.js

@@ -47,7 +47,8 @@ class TaskSession {
             intent: input.intent,
             participants: input.participants,
             ttlMs: input.ttlMs,
-            context: input.context,
+            contextId: input.contextId,
+            extensions: input.extensions,
             roots: input.roots,
             modeVersion: this.modeVersion,
             configurationVersion: this.configurationVersion,

package/dist/types.d.ts

@@ -45,6 +45,8 @@ export interface SessionMetadata {
     participants?: string[];
     participantActivity?: ParticipantActivity[];
     initiator?: string;
+    contextId?: string;
+    extensionKeys?: string[];
 }
 export interface ModeDescriptor {
     mode: string;
@@ -93,7 +95,8 @@ export interface SessionStartPayload {
     configurationVersion: string;
     policyVersion?: string;
     ttlMs: number;
-    context?: Buffer;
+    contextId?: string;
+    extensions?: Record<string, Buffer>;
     roots?: Root[];
 }
 export interface CommitmentPayload {
@@ -250,7 +253,7 @@ export interface PolicyDescriptor {
     policyId: string;
     mode: string;
     description: string;
-    rules: Buffer | Uint8Array;
+    rules: string;
     schemaVersion: number;
     registeredAtUnixMs?: number;
 }
@@ -261,3 +264,9 @@ export interface RegistryChanged {
 export interface RootsChanged {
     observedAtUnixMs: string;
 }
+export type SessionLifecycleEventType = 'EVENT_TYPE_UNSPECIFIED' | 'EVENT_TYPE_CREATED' | 'EVENT_TYPE_RESOLVED' | 'EVENT_TYPE_EXPIRED';
+export interface SessionLifecycleEvent {
+    eventType: SessionLifecycleEventType;
+    session: SessionMetadata;
+    observedAtUnixMs: string;
+}

package/dist/watchers.d.ts

@@ -1,6 +1,6 @@
 import type { AuthConfig } from './auth';
 import type { MacpClient } from './client';
-import type { Envelope, PolicyDescriptor, RegistryChanged, RootsChanged } from './types';
+import type { Envelope, PolicyDescriptor, RegistryChanged, RootsChanged, SessionLifecycleEvent } from './types';
 export declare class ModeRegistryWatcher {
     private readonly client;
     private readonly auth?;
@@ -45,3 +45,13 @@ export declare class PolicyWatcher {
     watch(handler: (change: PolicyChange) => void | Promise<void>): Promise<void>;
     nextChange(): Promise<PolicyChange>;
 }
+export declare class SessionLifecycleWatcher {
+    private readonly client;
+    private readonly auth?;
+    constructor(client: MacpClient, options?: {
+        auth?: AuthConfig;
+    });
+    events(signal?: AbortSignal): AsyncGenerator<SessionLifecycleEvent, void, void>;
+    watch(handler: (event: SessionLifecycleEvent) => void | Promise<void>): Promise<void>;
+    nextEvent(): Promise<SessionLifecycleEvent>;
+}

package/dist/watchers.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PolicyWatcher = exports.SignalWatcher = exports.RootsWatcher = exports.ModeRegistryWatcher = void 0;
+exports.SessionLifecycleWatcher = exports.PolicyWatcher = exports.SignalWatcher = exports.RootsWatcher = exports.ModeRegistryWatcher = void 0;
 function serverStreamToAsyncGenerator(stream) {
     const queue = [];
     let resolve = null;
@@ -174,3 +174,36 @@ class PolicyWatcher {
     }
 }
 exports.PolicyWatcher = PolicyWatcher;
+class SessionLifecycleWatcher {
+    client;
+    auth;
+    constructor(client, options) {
+        this.client = client;
+        this.auth = options?.auth;
+    }
+    async *events(signal) {
+        const stream = this.client.watchSessions(this.auth);
+        if (signal) {
+            signal.addEventListener('abort', () => stream.cancel(), { once: true });
+        }
+        const gen = serverStreamToAsyncGenerator(stream);
+        for await (const response of gen) {
+            if (response.event)
+                yield response.event;
+        }
+    }
+    async watch(handler) {
+        for await (const event of this.events()) {
+            await handler(event);
+        }
+    }
+    async nextEvent() {
+        const gen = this.events();
+        const result = await gen.next();
+        await gen.return(undefined);
+        if (result.done)
+            throw new Error('stream ended before receiving a session lifecycle event');
+        return result.value;
+    }
+}
+exports.SessionLifecycleWatcher = SessionLifecycleWatcher;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "macp-sdk-typescript",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "TypeScript SDK for the MACP Rust runtime",
   "license": "Apache-2.0",
   "type": "commonjs",
@@ -55,7 +55,7 @@
   "dependencies": {
     "@grpc/grpc-js": "^1.14.3",
     "@grpc/proto-loader": "^0.8.0",
-    "@multiagentcoordinationprotocol/proto": "^0.1.0",
+    "@multiagentcoordinationprotocol/proto": "^0.1.1",
     "protobufjs": "^8.0.0"
   },
   "devDependencies": {