@ziggs-ai/agent-sdk 0.42.0 → 0.43.0

package/dist/platform/ZiggsEffectHandler.js

@@ -1,53 +1,77 @@
+import { MessageRecordsClient } from '@ziggs-ai/api-client';
 import { OutboxBuffer } from './OutboxBuffer.js';
 import { runtimeLog } from '../shared/runtimeLog.js';
+import { resolveBackendUrl } from '../shared/backendUrl.js';
 import { toolFailureText } from '../brain/toolFailureText.js';
 import { ExecutionRefusal, executionControllers } from '../runtime/executionController.js';
-import { artifactScopeForSession } from '@ziggs-ai/api-client';
+import { assertRequiredContext } from '../runtime/requiredContext.js';
+import { artifactScope } from '@ziggs-ai/api-client';
 import { buildLlmIngestPayload, buildToolIngestPayload, isTelemetryIngestEnabled, sendTelemetry, } from './telemetryIngest.js';
 const CONTEXT_CACHE_MAX = 256;
-/**
- * Compose a `ContextSnapshot` for a chatId via the grant-fenced aggregate read
- * (`GET /context/snapshot`, follow-up). The backend assembles history +
- * agreements + roster through the same `assertScopeAccess` + temporal fence as
- * the per-type context reads, and annotates `*IsYou` / self server-side against
- * the acting agent. This function only preserves the never-throw/degrade
- * contract that the cognition code depends on — the shape is unchanged.
- */
-const emptySnapshot = (agentId, chatMissing = false) => ({
+/** Said in place of a read when nothing selects one. Not a failure: the wake can still act on explicit resources. */
+const NO_CONTEXT = 'This wake selects no message, artifact or work. Name an exact message, artifact, task or agreement before reading context.';
+/** Required work context and optional messaging inputs share the same access
+ * checks, but are fetched independently. */
+const emptySnapshot = (agentId) => ({
     history: [],
     agreements: [],
     users: [],
     agents: [{ agentId, role: 'self', isYou: true, kind: 'agent' }],
     latestSequence: null,
-    ...(chatMissing ? { chatMissing: true } : {}),
 });
-async function buildSnapshot(deps, chatId, agentId, opts = {}) {
+async function buildSnapshot(deps, agentId, opts = {}) {
     try {
-        // Server returns 200 + chatMissing:true for a deleted chat, so its
-        // annotations (roster, *IsYou, self) are already applied — pass through.
-        // Read as this wake: the session is the lane, the way its tool calls are
-        // sent. Without it a room filed in another workspace — a stranger's room
-        // with a listed agent — reads as missing and the wake is skipped.
-        const reader = deps.contextReadClient;
-        const snap = await reader.snapshot(chatId, {
-            maxMessages: opts.limit,
-            ...opts.workScope,
+        const scope = opts.workScope;
+        const via = opts.via ?? (scope?.taskId ? `task:${scope.taskId}` : scope?.agreementId ? `agreement:${scope.agreementId}` : scope?.messageId ? `message:${scope.messageId}` : scope?.artifactId ? `artifact:${scope.artifactId}` : undefined);
+        if (!via)
+            throw new Error('Context requires an explicit message, artifact, task or agreement');
+        const agreementId = scope?.agreementId ?? (via.startsWith('agreement:') ? via.slice('agreement:'.length) : undefined);
+        const messageId = scope?.messageId ?? (via.startsWith('message:') ? via.slice('message:'.length) : undefined);
+        // Select the work independently of its triggering message. A message is
+        // the snapshot entry only when it is the selected resource itself.
+        const snap = await deps.contextReadClient.snapshot({
+            via, maxMessages: opts.limit,
+            ...(agreementId ? { agreementId } : {}),
+            ...(scope?.artifactId ? { artifactId: scope.artifactId } : {}),
         });
-        // Built rather than cast: the roster rows are typed on both sides now (they
-        // carry the declared participant kind), and only `history` is loose on the
-        // wire, so a whole-object cast would be asserting past the one field that
-        // actually needs it.
-        return { ...snap, history: snap.history };
+        assertRequiredContext(snap);
+        const messages = new MessageRecordsClient(deps.operatorKey, agentId, resolveBackendUrl());
+        const trigger = messageId ? await messages.get(messageId) : undefined;
+        if (trigger && agreementId && trigger.mandate?.agreementId !== agreementId)
+            throw Object.assign(new Error('Trigger belongs to different work'), { status: 403 });
+        if (trigger && opts.workScope?.taskId && trigger.mandate?.taskId !== opts.workScope.taskId)
+            throw Object.assign(new Error('Trigger belongs to different task work'), { status: 403 });
+        const present = (m) => ({ messageId: m.messageId, text: m.content.text, entryType: 'message', timestamp: Date.parse(m.timestamp), sender: { id: m.sender.isSelf ? agentId : m.sender.ref, type: m.sender.kind }, receiver: { id: m.recipients[0]?.ref } });
+        const required = trigger ? [present(trigger)] : [];
+        const context = { ...snap, messageRecord: trigger, messageMandate: agreementId ? { agreementId, ...(opts.workScope?.taskId ? { taskId: opts.workScope.taskId } : {}) } : trigger?.mandate ?? undefined };
+        if (trigger || agreementId) {
+            if (opts.includeHistory === true) {
+                try {
+                    const page = agreementId ? await messages.list({ agreementId, taskId: opts.workScope?.taskId, limit: Math.min(opts.limit ?? 12, 30) }) : await messages.replies(trigger.messageId, { limit: Math.min(opts.limit ?? 12, 30) });
+                    const history = page.messages.map(present);
+                    if (trigger && !page.messages.some(m => m.messageId === trigger.messageId))
+                        history.unshift(present(trigger));
+                    return { ...context, history };
+                }
+                catch (error) {
+                    const refusal = error;
+                    if (refusal.status === 401 || refusal.code?.startsWith('EXECUTION_'))
+                        throw error;
+                    return { ...context, history: required, historyUnavailable: true };
+                }
+            }
+            return { ...context, history: required };
+        }
+        return { ...snap, history: snap.history.map(present) };
     }
     catch (err) {
-        // Defensive: server normally signals a dead chat as 200 + chatMissing, but
-        // a raw 404 degrades the same way so message wakes still skip it.
+        // A refused/missing exact resource is required context failure.
         const status = err?.status;
         // 403 = exists but this agent has no grant. Same as deleted:
         // no world to act in. Leaving it as an empty snapshot used to run a
         // full turn against refusals.
         if (status === 404 || status === 403) {
-            return { ...emptySnapshot(agentId, true), unavailable: true, work: { minimumComplete: false, authorization: { active: false }, instruction: 'Required context is unavailable. Do not start work without verified scope and access.' } };
+            return { ...emptySnapshot(agentId), unavailable: true, work: { minimumComplete: false, authorization: { active: false }, instruction: 'Required context is unavailable. Do not start work without verified scope and access.' } };
         }
         runtimeLog.warn('ZiggsEffectHandler', `snapshot fetch failed: ${err?.message ?? err}`);
         return { ...emptySnapshot(agentId), unavailable: true, work: { minimumComplete: false, authorization: { active: false }, instruction: 'Context read failed. Retry or request access before acting; an empty packet is not permission.' } };
@@ -85,15 +109,18 @@ function previewToolArgs(args) {
  * Chat timeline: `Message.tsx` parses `entryType: artifact`, `contentType: operation` with
  * `operation_*:{json}` where json includes `state` and `tool`.
  */
-async function emitToolOperationArtifact(client, sessionId, phase, payload, idempotencyKey, serviceAgreementId, taskId) {
+async function emitToolOperationArtifact(client, addressId, phase, payload, idempotencyKey, serviceAgreementId, taskId) {
+    // Operation history belongs to selected work or an explicit conversation.
+    // An unbound processing lane must not accumulate shared private context.
+    if (!addressId && !serviceAgreementId && !taskId)
+        return;
     const prefix = phase === 'started' ? 'operation_started' : phase === 'completed' ? 'operation_completed' : 'operation_error';
     const text = `${prefix}:${JSON.stringify(payload)}`;
     try {
         await client.write({
-            // an agreement lane (`agrn-…`) is a routing key, not a chat —
-            // passing it as chatId asked the backend to write into a chat that does
-            // not exist and 403'd every breadcrumb on agreement-lane work.
-            ...artifactScopeForSession(sessionId),
+            // The wake's own conversation or work. A processing lane is a routing
+            // key, never a chat: a breadcrumb with neither is refused here.
+            ...artifactScope({ agreementId: serviceAgreementId }),
             text,
             contentType: 'operation',
             visibility: 'agent-private',
@@ -119,12 +146,15 @@ async function emitToolOperationArtifact(client, sessionId, phase, payload, idem
  * side effects — that is the whole point of funneling both paths here.
  *
  * `eff` is threaded into the tool context so eff-backed tools
- * (`context_snapshot`, `chat_send`) resolve through this same path
+ * (`context_snapshot`, `message_send`) resolve through this same path
  * regardless of which cognition invoked them.
  */
 export async function executeToolWithSideEffects(deps, eff, effect, roster) {
     const toolT0 = Date.now();
     let args = effect.args || {};
+    // The wake's explicit conversation, when it has one. The effect's session
+    // is the processing lane, which routes effects and is never an address.
+    const addressId = deps.conversationFor?.(effect.sessionId)?.addressId;
     const controller = executionControllers.getStore();
     let binding;
     let argsPreview;
@@ -142,7 +172,7 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
             args = Object.fromEntries(Object.entries(args).filter(([key]) => key !== 'taskId'));
         }
         argsPreview = previewToolArgs(args);
-        void emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'started', {
+        void emitToolOperationArtifact(deps.artifactsClient, addressId, 'started', {
             state: 'started',
             tool: effect.name,
             ...(argsPreview ? { args: argsPreview } : {}),
@@ -166,7 +196,8 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
         const result = await deps.toolManager.executeTool(effect.name, args, {
             operatorKey: deps.operatorKey,
             agentId: deps.agentId,
-            chatId: effect.sessionId,
+            ...(addressId ? { addressId } : {}),
+            sessionId: effect.sessionId,
             taskService: deps.taskService,
             agreementService: deps.agreementService,
             contextReadClient: deps.contextReadClient,
@@ -195,7 +226,7 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
         // One clip per tool call: this is a full JSON.stringify of the untruncated
         // result, and the artifact body and the idempotency key want the same string.
         const clipped = clipForOperationArtifact(result);
-        void emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'completed', {
+        void emitToolOperationArtifact(deps.artifactsClient, addressId, 'completed', {
             state: 'completed',
             tool: effect.name,
             result: clipped,
@@ -213,7 +244,7 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
     catch (error) {
         const errMsg = toolFailureText(error);
         runtimeLog.warn('ZiggsEffectHandler', `tool-call "${effect.name}" failed: ${errMsg}`);
-        void emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'error', {
+        void emitToolOperationArtifact(deps.artifactsClient, addressId, 'error', {
             state: 'failed',
             tool: effect.name,
             error: errMsg,
@@ -265,7 +296,17 @@ export function createZiggsEffectHandler(deps) {
                 // the per-type reads. Every producer — ClaudeBrain.tick, runTurn,
                 // and the on-demand context_snapshot tool — routes through here.
                 const scopes = effect.opts?.workScopes ?? [];
-                const packets = await Promise.all((scopes.length ? scopes : [undefined]).map(workScope => buildSnapshot(deps, effect.sessionId, deps.agentId, { limit: effect.opts?.maxMessages, workScope })));
+                const destination = deps.conversationFor?.(effect.sessionId);
+                const defaultScope = destination ? { agreementId: destination.agreementId, taskId: destination.taskId, messageId: destination.message?.messageId } : undefined;
+                const selects = (scope) => !!(effect.opts?.via || scope?.agreementId || scope?.taskId || scope?.messageId);
+                if (!scopes.length && !selects(defaultScope)) {
+                    const none = { ...emptySnapshot(deps.agentId), work: { instruction: NO_CONTEXT } };
+                    cachePut(effect.sessionId, none);
+                    return none;
+                }
+                // An explicit resource read never inherits another wake's work selection.
+                const selectedScopes = scopes.length ? scopes : [effect.opts?.via ? undefined : defaultScope];
+                const packets = await Promise.all(selectedScopes.map(workScope => buildSnapshot(deps, deps.agentId, { limit: effect.opts?.maxMessages, workScope, via: effect.opts?.via, includeHistory: effect.opts?.includeHistory })));
                 const snap = packets.length === 1 ? packets[0] : {
                     ...emptySnapshot(deps.agentId),
                     work: { contexts: packets.map(p => ({ ...p.work, workBrief: p.workBrief, agreements: p.agreements, history: p.history, artifacts: p.artifacts })),
@@ -336,33 +377,23 @@ export function createZiggsEffectHandler(deps) {
                 });
             }
             case 'send-message': {
-                const sent = await deps.messageSender(effect.text, effect.receiverId, effect.sessionId, effect.messageId, effect.conversationAgreementId, effect.underAgreementId, effect.taskId, effect.sources);
-                outbox.track(effect.sessionId, { text: effect.text, receiverId: effect.receiverId });
-                // Carry the send's own report back to whoever asked for the send. A
-                // sender that cannot see where its message went cannot tell a delivered
-                // answer from a dropped one, which is the whole failure here.
-                const report = (sent ?? {});
-                return {
-                    ok: true,
-                    ...(report.chatId ? { chatId: report.chatId } : {}),
-                    ...(report.messageId ? { messageId: report.messageId } : {}),
-                    ...(report.delivered ? { delivered: report.delivered } : {}),
-                    ...(report.to ? { to: report.to } : {}),
-                };
+                const sent = await deps.messageSender(effect.command);
+                outbox.track(effect.sessionId, { text: effect.command.content.text, receiverId: sent.message.recipients[0]?.ref });
+                return { ...sent, ok: true };
             }
             case 'record-event': {
                 // Routes through ArtifactsClient as an agent-private artifact —
                 // visible to this agent across turns, not to other chat parties.
                 try {
                     if (effect.entry.kind === 'thought' && typeof effect.entry.text === 'string') {
-                        await deps.artifactsClient.recordThought(effect.sessionId, effect.entry.text, {
+                        await deps.artifactsClient.recordThought(effect.entry.text, {
                             idempotencyKey: effect.idempotencyKey,
                             serviceAgreementId: effect.serviceAgreementId,
                         });
                     }
                     else {
                         await deps.artifactsClient.write({
-                            ...artifactScopeForSession(effect.sessionId),
+                            ...artifactScope({ agreementId: effect.serviceAgreementId }),
                             text: JSON.stringify(effect.entry),
                             contentType: String(effect.entry.kind ?? 'event'),
                             visibility: 'agent-private',

package/dist/platform/agreements/AgreementService.d.ts

@@ -1,4 +1,4 @@
-import { type Agreement, type ClaimedKind, type ClaimOptions, type ProposeAgreementData, type ProposeDirectInput, type ProposeBroadcastInput, type PublishOfferPayload, type UnifiedProposeInput, type ProposeShape, type DelegateAgreementData, type CounterAgreementData, type CreateLinkBody, type CreateLinkResult, type ListAgreementsFilters, type GetMyAgreementsFilters, type ChatLinkType, type ArtifactLinkType } from '@ziggs-ai/api-client';
+import { type Agreement, type ClaimedKind, type ClaimOptions, type ProposeAgreementData, type ProposeDirectInput, type ProposeBroadcastInput, type PublishOfferPayload, type UnifiedProposeInput, type ProposeShape, type DelegateAgreementData, type CounterAgreementData, type CreateLinkBody, type CreateLinkResult, type ListAgreementsFilters, type GetMyAgreementsFilters, type ArtifactLinkType } from '@ziggs-ai/api-client';
 export declare class AgreementService {
     private creds;
     constructor(operatorKey: string, agentId: string);
@@ -79,8 +79,6 @@ export declare class AgreementService {
         ok: boolean;
         agreement: Agreement;
     }>;
-    linkToChat(agreementId: string, chatId: string, linkType?: ChatLinkType): Promise<unknown | null>;
-    getChats(agreementId: string): Promise<unknown[]>;
     linkArtifact(agreementId: string, artifactId: string, linkType?: ArtifactLinkType): Promise<unknown | null>;
     getArtifacts(agreementId: string): Promise<unknown[]>;
 }

package/dist/platform/agreements/AgreementService.js

@@ -1,4 +1,4 @@
-import { proposeAgreement, proposeBroadcast as proposeBroadcastApi, delegateAgreement, respondToAgreement, counterAgreement, claimOpenAgreement, proposeUnified, getAgreementStatus, listAgreements, getMyAgreements, getAgreement, publishOffer as publishOfferApi, createLink, revokeAgreement, fulfillAgreement, linkAgreementToChat, getChatsForAgreement, linkArtifactToAgreement, getArtifactsForAgreement, } from '@ziggs-ai/api-client';
+import { proposeAgreement, proposeBroadcast as proposeBroadcastApi, delegateAgreement, respondToAgreement, counterAgreement, claimOpenAgreement, proposeUnified, getAgreementStatus, listAgreements, getMyAgreements, getAgreement, publishOffer as publishOfferApi, createLink, revokeAgreement, fulfillAgreement, linkArtifactToAgreement, getArtifactsForAgreement, } from '@ziggs-ai/api-client';
 export class AgreementService {
     creds;
     constructor(operatorKey, agentId) {
@@ -105,12 +105,6 @@ export class AgreementService {
     fulfill(agreementId) {
         return fulfillAgreement(agreementId, this.creds);
     }
-    linkToChat(agreementId, chatId, linkType = 'mention') {
-        return linkAgreementToChat(agreementId, chatId, linkType, this.creds);
-    }
-    getChats(agreementId) {
-        return getChatsForAgreement(agreementId, this.creds);
-    }
     linkArtifact(agreementId, artifactId, linkType = 'produced') {
         return linkArtifactToAgreement(agreementId, artifactId, linkType, this.creds);
     }

package/dist/platform/inboxLoop.d.ts

@@ -1,5 +1,6 @@
-import { type InboxChatNews, type InboxRequestRef, type InboxTaskRef, type Creds } from '@ziggs-ai/api-client';
+import { type InboxRequestRef, type InboxTaskRef, type Creds } from '@ziggs-ai/api-client';
 import { SeenMessages } from './SeenMessages.js';
+import type { TaskInputRef } from '../types.js';
 /**
  * Per-agent inbox long-poll loop (delivery law, phase 4). This is the ONLY way
  * a hosted agent consumes: `GET /inbox?wait=` → grant-fenced reads of what was
@@ -25,13 +26,15 @@ export interface InboxLoopDeps {
      * own task channel, so work reaches the agent even when no chat row exists
      * for it (chat-less agreement, self-assigned task).
      */
-    onTask?: (task: InboxTaskRef) => Promise<void>;
+    onTask?: (task: InboxTaskRef, inputs: TaskInputRef[]) => Promise<void>;
     /**
      * A marketplace request doorbell. The host MUST triage with a plain
      * string compare and return without an LLM wake on miss — otherwise every
      * public request burns a full Claude turn per published supplier.
      */
     onRequest?: (request: InboxRequestRef) => Promise<void>;
+    /** Host-only control observation for blocked task assignments; never a model wake. */
+    onTaskControlCheck?: (taskId: string) => Promise<void>;
     label?: string;
 }
 export interface InboxPassResult {
@@ -60,13 +63,6 @@ export interface InboxPassResult {
      */
     blocked: number;
 }
-/**
- * A capability probe waits on a `probe_*` chat reply, not inbox ack. Act
- * those rooms before leftover mail so a standing host answers the gate
- * even when the envelope also carries older chats. The prefix only orders
- * the wake — it does not buy a canned answer.
- */
-export declare function chatsInWakeOrder(chats: InboxChatNews[]): InboxChatNews[];
 /**
  * One long-poll pass: hold up to `waitSeconds` for new inbox content, then read
  * the deltas, deliver them into the host, and ack. Returns what it delivered.