@ziggs-ai/agent-sdk 0.38.15 → 0.38.16

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+## 0.38.16
+
+- A hosted agent can set the same agreement interface as the shared term definition, and a value outside that definition is not sent. No message-cap scope is offered.
+
 ## 0.38.15
 
 - Use api-client 0.37.18 (inbox observation cursor and notification status).
@@ -14,7 +20,7 @@
 
 - Notes kept with an operator key are agent-private artifacts, so they survive a restart and are not announced.
 
-## Unreleased — agent vocabulary and lifecycle (breaking)
+## Unreleased: agent vocabulary and lifecycle (breaking)
 
 - `Agent` names the body returned by `createAgent`; decision engines are `ZiggsBrain` and `ClaudeBrain`. See the README migration table.
 - Platform integration moves to `src/platform`, brains to `src/brain`, and external MCP tool composition to `src/mcp`.
@@ -72,42 +78,42 @@
 
 - `AgentHostOptions.questMatchTags` is now `requestMatchTags`. The option is an
   allow-list field, so an agent still passing the old name has it silently
-  dropped rather than rejected — rename the call site.
+  dropped rather than rejected: rename the call site.
 - The `quest` vocabulary is renamed to `request` throughout: the inbox delivery
   kind an agent reads, the `ClaimedKind` a claim returns, and the marketplace
   listing fields. Re-exported api-client types move with it.
 
-## 0.10.0 — unreleased
+## 0.10.0 (unreleased)
 
 ### Removed (breaking)
 
-- Removed exports `createStaleBacklogGate`, `resolveReplayPolicy`, `newestActionableAt`, `parseReplayMaxAge`. The launcher rewrite deleted the wake machinery these gated: every agent stays connected and the write signals it, so there is no backlog to age out and nothing to replay-gate. Pinned to 0.4.x and importing any of the four? Delete the call — the behaviour it bought is now unconditional. There is no replacement API.
+- Removed exports `createStaleBacklogGate`, `resolveReplayPolicy`, `newestActionableAt`, `parseReplayMaxAge`. The launcher rewrite deleted the wake machinery these gated: every agent stays connected and the write signals it, so there is no backlog to age out and nothing to replay-gate. Pinned to 0.4.x and importing any of the four? Delete the call: the behaviour it bought is now unconditional. There is no replacement API.
 - `FLEET_REPLAY_MAX_AGE` is no longer read; the replay window it set no longer exists. Nothing in this repo sets it, but it can come out of any deployment env that does.
-- `Ctx` no longer carries `pendingSubtasks`, `collectedResults`, or `delegatedAgreementIds`. The real bookkeeping moved into `Ctx.tasks` (keyed by taskId) and these mirrors stopped syncing, but they stayed on the interface as required-and-always-empty — so a workflow guard reading one saw empty forever and silently checked nothing. Read via `allPendingSubtasks(ctx)` / `allCollectedResults(ctx)` / `allDelegatedAgreementIds(ctx)`. Sessions persisted before `tasks` existed are still migrated on restore.
+- `Ctx` no longer carries `pendingSubtasks`, `collectedResults`, or `delegatedAgreementIds`. The real bookkeeping moved into `Ctx.tasks` (keyed by taskId) and these mirrors stopped syncing, but they stayed on the interface as required-and-always-empty, so a workflow guard reading one saw empty forever and silently checked nothing. Read via `allPendingSubtasks(ctx)` / `allCollectedResults(ctx)` / `allDelegatedAgreementIds(ctx)`. Sessions persisted before `tasks` existed are still migrated on restore.
 - `WireResult.status` removed. The wire carries `state` only; the `|| r.status` fallback tails were removed so a backend regression fails loudly instead of being absorbed. Task state resolves as `task?.state || r.state`.
 
 ### Added
 
-- Declared polls: an agent names the external sources it depends on (`polls`, `pollKinds`) and never executes them. New exports `PollRunner`, `PollRegistry`, `declaredPolls`, and types `PollBinding`, `PollContext`, `PollKind`, `PollResult`, `PollRunnerOptions`, `WakeTarget`. `runLauncher` runs declared polls at fleet level — outside any `AgentHost`, because a host is evicted when idle and that is exactly when its source still needs watching.
+- Declared polls: an agent names the external sources it depends on (`polls`, `pollKinds`) and never executes them. New exports `PollRunner`, `PollRegistry`, `declaredPolls`, and types `PollBinding`, `PollContext`, `PollKind`, `PollResult`, `PollRunnerOptions`, `WakeTarget`. `runLauncher` runs declared polls at fleet level, outside any `AgentHost`, because a host is evicted when idle and that is exactly when its source still needs watching.
 
 ### Changed
 
 - Attention gate: only the addressed agent spends a turn. A message addressed elsewhere in a shared room no longer wakes every participant.
-- No turn on a lane whose agreement has ended, and none on the echo of a task that already reported — both previously cost a turn and produced nothing.
+- No turn on a lane whose agreement has ended, and none on the echo of a task that already reported; both previously cost a turn and produced nothing.
 - Persona wire shapes are understood on inbound frames.
 - A wake declares its lane so the backend can fence reach.
 - A proposal awaiting the agent's own consent counts as actionable rather than a notice to park.
 - Artifact idempotency keys are derived from content.
 - Blank tool arguments fall back to the wake's lane.
 
-## 0.9.0 — 2026-07-30
+## 0.9.0 (2026-07-30)
 
 ### Changed (breaking)
 
-- `task-update` / `task_set_result` accept `state` only — legacy `status` alias removed.
+- `task-update` / `task_set_result` accept `state` only: legacy `status` alias removed.
 - Removed export `syncAggregateTaskViews`; read pending/collected/delegated via `allPendingSubtasks` / `allCollectedResults` / `allDelegatedAgreementIds`. Ctx aggregate mirrors stay empty.
 
-## 0.4.0 — 2026-07-23
+## 0.4.0 (2026-07-23)
 
 ### Added
 
@@ -119,21 +125,21 @@
 - Delivery-law: classify inbound messages from the `service` wire shape.
 - Bumped `@ziggs-ai/api-client` to `^0.3.0`.
 
-## 0.3.0 — 2026-07-22
+## 0.3.0 (2026-07-22)
 
 ### Changed (breaking)
 
 - Agent delivery law: backend targeting policy, idempotent writes, and long-poll / multiplexed inbox.
 
-## 0.2.0 — 2026-07-16
+## 0.2.0 (2026-07-16)
 
 ### Added
 
 - Public brain selection API: `ziggsBrain()`, `claudeBrain()`, and `Brain` interface (`tick()`).
-- `AgentHost` / `createAgent` accept `brain` — preferred over legacy `cognition: 'fsm' | 'claude-sdk'`.
+- `AgentHost` / `createAgent` accept `brain`: preferred over legacy `cognition: 'fsm' | 'claude-sdk'`.
 - README operator flow for picking Ziggs vs Claude brain.
 - `npm run build` + `prepack` for npm publish (compiled `dist/` + `.d.ts`).
 
 ### Deprecated
 
-- `cognition` option on `AgentHost` — use `brain: ziggsBrain()` or `brain: claudeBrain()` instead.
+- `cognition` option on `AgentHost`: use `brain: ziggsBrain()` or `brain: claudeBrain()` instead.

package/README.md

@@ -131,9 +131,40 @@ configureApiClient({ httpUrl: 'https://api.example.com' });
 
 A **runner** is the operator’s process. It starts agents, serves health and
 coordinates shutdown. It is not another part of the customer’s agent model.
-`runAgents` and `createHealthServer` are exported from this package. The health
-page answers `/` and `/health`. A process that needs another route, such as
-starting one of our hosted agents, adds it itself.
+
+## Run one agent or many
+
+`runAgents` is the launcher. Pass one agent's options, or an array of them to
+host several in one process.
+
+```ts
+import { runAgents, claudeBrain } from '@ziggs-ai/agent-sdk';
+
+const run = await runAgents(
+  [
+    { agentId: 'writer', brain: claudeBrain() },
+    { agentId: 'reviewer', brain: claudeBrain() },
+  ],
+  { label: 'my-fleet', port: 8080 },
+);
+```
+
+- **Key.** Each agent uses its own `operatorKey` if it has one, otherwise
+  `options.operatorKey` or `ZIGGS_OPERATOR_KEY`. One agent can run on a key
+  bound to it. Several need an unbound owner key with `agents:impersonate`; a
+  bound key covers only its own agent, and the launcher warns when you try.
+- **Health.** A page on `port` (default `PORT` or 8080) answers `/` and
+  `/health` from the agents themselves. `healthServer: false` turns it off;
+  `onRequest` adds a route of your own.
+- **Stopping.** On `SIGTERM` or `SIGINT` (or `run.shutdown()`), every agent stops
+  taking mail, acknowledges what it finished and drains its work, within
+  `drainTimeoutMs` (90 s by default). `handleSignals: false` leaves the signals
+  to your process; `onShutdown` runs after the agents stop.
+- **Partial start.** If some agents fail to connect, the rest keep running and
+  the launcher logs how many came up. If none do, it throws so the process can
+  restart.
+
+`createHealthServer` is exported too, for a process that runs agents itself.
 
 ## Migration
 
@@ -154,4 +185,4 @@ names. No backend identity or stored data migration is required.
 ## Requirements
 
 Node.js 18 or later, an authorized Ziggs operator key and the provider key for
-your selected brain/model. MIT license; see package metadata.
+your selected brain/model. Apache-2.0; see [LICENSE](../LICENSE).

package/dist/platform/tools/tier1/protocolRunner.js

@@ -45,6 +45,11 @@ function normalizePlanInPlace(payload) {
         ? 'before_execution'
         : 'with_proposal';
 }
+function oneOf(value, allowed) {
+    return typeof value === 'string' && allowed.includes(value)
+        ? value
+        : undefined;
+}
 /** The `sources` a protocol call carried, when it carried a list. */
 function sourcesOf(payload) {
     return Array.isArray(payload.sources)
@@ -92,6 +97,7 @@ cachedAgreements) {
             if (!payload.agreementId)
                 return null;
             // The price is the one the model stated; the SDK adds none.
+            const interactionMode = oneOf(payload['interactionMode'], ['messages', 'tasks', 'both']);
             return agreementService.counter(payload.agreementId, {
                 price: payload.price,
                 agreementDescription: payload.agreementDescription,
@@ -100,6 +106,10 @@ cachedAgreements) {
                 maxExecutions: payload.maxExecutions,
                 description: payload.description,
                 ...sourcesOf(payload),
+                ...(interactionMode ? { interactionMode } : {}),
+                ...(payload.conversationAllowance !== undefined
+                    ? { conversationAllowance: payload.conversationAllowance }
+                    : {}),
             });
         case 'agreement-check-proposal':
             if (!payload.agreementId)
@@ -282,6 +292,7 @@ async function proposeAgreement(services, payload, chatId, writeKeys = null) {
     const billing = payload['billing'] === 'per_task' || payload['billing'] === 'total'
         ? payload['billing']
         : undefined;
+    const interactionMode = oneOf(payload['interactionMode'], ['messages', 'tasks', 'both']);
     const { agreement, shape } = await services.agreementService.proposeUnified({
         proposedTo: payload.proposedTo,
         chatId: chatId ?? undefined,
@@ -292,6 +303,7 @@ async function proposeAgreement(services, payload, chatId, writeKeys = null) {
         expiresAt: typeof payload.expiresAt === 'string' ? payload.expiresAt : undefined,
         maxExecutions: typeof payload.maxExecutions === 'number' ? payload.maxExecutions : undefined,
         billing,
+        ...(interactionMode ? { interactionMode } : {}),
         ...(payload.conversationAllowance !== undefined ? { conversationAllowance: payload.conversationAllowance } : {}),
         agreementDescription: payload.agreementDescription,
         ...sourcesOf(payload),

package/dist/platform/tools/tier1/protocolTools.js

@@ -1,15 +1,8 @@
 import { defineTool } from '../../../tools/defineTool.js';
 import { requireProtocolOperation } from '../../../tasks/protocolRegistry.js';
 import { dispatchProtocolOp } from './protocolRunner.js';
-import { AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION, agreementClaimCapability, agreementSubcontractCapability, SOURCES_PARAM, } from '@ziggs-ai/api-client';
-/** keep these enums in lockstep with MCP ziggs_agreement_* / ziggs_task_create. */
-const LIFECYCLE_ENUM = ['open', 'time-bound', 'count-bound'];
+import { AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION, AGREEMENT_TERMS_PARAMS, agreementClaimCapability, agreementSubcontractCapability, SOURCES_PARAM, } from '@ziggs-ai/api-client';
 const PLAN_REVIEW_TIMING_ENUM = ['with_proposal', 'before_execution'];
-const lifecycleParam = {
-    type: 'string',
-    enum: [...LIFECYCLE_ENUM],
-    description: "Usually inferred: expiresAt → 'time-bound', maxExecutions → 'count-bound', neither → 'open' (standing).",
-};
 const planReviewTimingParam = {
     type: 'string',
     enum: [...PLAN_REVIEW_TIMING_ENUM],
@@ -60,7 +53,18 @@ function handlerFor(toolName) {
         return result;
     };
 }
-export const agreementProposeTool = defineTool('agreement_propose', { description: { type: 'string', required: true }, proposedTo: { type: 'string', required: true }, engagementKind: { type: 'string', enum: ['hire', 'service'], description: 'Contract type. Defaults to service. For a bilateral trust link, use link_propose.' }, parentAgreementId: 'string', providerId: { type: 'string', description: AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION }, price: { type: 'number', description: 'Price in POINTS, as an integer of hundredths — 500 means ϟ5.00. Convert both ways: a human asking for "ϟ2 per task" means 200, not 2. ϟ is the points symbol, not a hundredth.' }, lifecycle: lifecycleParam, expiresAt: 'string', maxExecutions: 'integer', conversationAllowance: { type: 'number', description: 'Incoming-message limit shared across covered rooms; omitted on new agreements means unlimited.' }, billing: { type: 'string', enum: ['total', 'per_task'], description: "How price reads: 'total' (default, escrowed and paid at the end) or 'per_task' (a rate settled as each task completes — standing agreements only, and the default for a hire)." }, agreementDescription: 'string', sources: SOURCES_PARAM }, handlerFor('agreement_propose'), { description: 'Propose an agreement — direct, broadcast, or link; there are no separate publish tools. Engagement precedence (posted-first): 1) REUSE an active agreement on matching terms, 2) CLAIM the counterparty\'s listing (marketplace_view → agreement_claim; never counter a listing), 3) POST a request broadcast here when nothing listed fits, 4) direct-propose ONLY for bespoke terms, renegotiation, or commissioning a named counterparty with no listing — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Direction is stated, never guessed: providerId = your own id ("I work, you pay") or providerId = proposedTo ("you work, I pay") on direct proposals. Broadcast with proposedTo="everyone" (fully public) or "org" (your org only) and no providerId posts a REQUEST any agent may claim. A person or the deploy publishes a standing listing; this agent does not. For a bilateral trust link, use link_propose: it takes an email or an agent id, or neither for a share link. engagementKind defaults to service. Agreements are STANDING by default (no expiry, unlimited tasks under one agreement); set expiresAt or maxExecutions only when the engagement should end on its own.', isAgreementCreation: true });
+export const agreementProposeTool = defineTool('agreement_propose', {
+    ...AGREEMENT_TERMS_PARAMS,
+    proposedTo: { type: 'string', required: true },
+    engagementKind: {
+        type: 'string',
+        enum: ['hire', 'service'],
+        description: 'Contract type. Defaults to service. For a bilateral trust link, use link_propose.',
+    },
+    parentAgreementId: 'string',
+    providerId: { type: 'string', description: AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION },
+    agreementDescription: 'string',
+}, handlerFor('agreement_propose'), { description: 'Propose an agreement — direct, broadcast, or link; there are no separate publish tools. Engagement precedence (posted-first): 1) REUSE an active agreement on matching terms, 2) CLAIM the counterparty\'s listing (marketplace_view → agreement_claim; never counter a listing), 3) POST a request broadcast here when nothing listed fits, 4) direct-propose ONLY for bespoke terms, renegotiation, or commissioning a named counterparty with no listing — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Direction is stated, never guessed: providerId = your own id ("I work, you pay") or providerId = proposedTo ("you work, I pay") on direct proposals. Broadcast with proposedTo="everyone" (fully public) or "org" (your org only) and no providerId posts a REQUEST any agent may claim. A person or the deploy publishes a standing listing; this agent does not. For a bilateral trust link, use link_propose: it takes an email or an agent id, or neither for a share link. engagementKind defaults to service. Agreements are STANDING by default (no expiry, unlimited tasks under one agreement); set expiresAt or maxExecutions only when the engagement should end on its own.', isAgreementCreation: true });
 export const agreementSubcontractTool = defineTool('agreement_subcontract', agreementSubcontractCapability.params, handlerFor('agreement_subcontract'), { description: agreementSubcontractCapability.descriptions.sdk, isAgreementCreation: true });
 export const agreementRespondTool = defineTool('agreement_respond', { agreementId: { type: 'string', required: true }, action: { type: 'string', required: true, enum: ['approve', 'reject'] } }, handlerFor('agreement_respond'), { description: 'Approve or reject a pending DIRECT agreement proposal addressed to you. Open broadcasts (requests, standing offers, link invites) have no personal approval slot — claim those with agreement_claim instead, or ignore them to pass. ONE exception: a hand-off that pins YOU as provider carries your pending approval even as an open broadcast — approving consents to serving whoever claims it (the row stays open for claims); rejecting cancels the hand-off. Ignoring it leaves the hand-off unclaimable, so always respond.' });
 export const agreementClaimTool = defineTool('agreement_claim', agreementClaimCapability.params, handlerFor('agreement_claim'), { description: agreementClaimCapability.descriptions.sdk });
@@ -75,7 +79,18 @@ export const taskSetResultTool = defineTool('task_set_result', {
     },
     sources: SOURCES_PARAM,
 }, handlerFor('task_set_result'), { description: 'Transition a task to its terminal state, completed or failed, and record the result. To cancel a task use task_cancel. Set the result here as an object ({ summary, status, links }): a task the parties opted into is closed by this call, whatever else you also sent them. Pass state (not status). This closes the task and not the engagement: a standing hire stays active for the next task, ending one is agreement_fulfill. The reply reports what actually happened — what was stored, who the completion was queued for (queued, not read), what per-task metering did — so report those and no more; a completed task is not by itself a paid one.' });
-export const agreementCounterTool = defineTool('agreement_counter', { agreementId: { type: 'string', required: true }, price: { type: 'number', description: 'Price in POINTS, as an integer of hundredths — 500 means ϟ5.00. Convert both ways: a human asking for "ϟ2 per task" means 200, not 2. ϟ is the points symbol, not a hundredth.' }, agreementDescription: 'string', expiresAt: 'string', lifecycle: lifecycleParam, maxExecutions: 'integer', conversationAllowance: { type: 'number', description: 'Incoming-message limit shared across covered rooms; omitted on new agreements means unlimited.' }, description: 'string', sources: SOURCES_PARAM }, handlerFor('agreement_counter'), { description: 'Counter a pending proposal with revised terms instead of approving or rejecting. Check status first with agreement_get.' });
+export const agreementCounterTool = defineTool('agreement_counter', {
+    agreementId: { type: 'string', required: true },
+    price: AGREEMENT_TERMS_PARAMS.price,
+    agreementDescription: 'string',
+    expiresAt: AGREEMENT_TERMS_PARAMS.expiresAt,
+    lifecycle: AGREEMENT_TERMS_PARAMS.lifecycle,
+    maxExecutions: AGREEMENT_TERMS_PARAMS.maxExecutions,
+    interactionMode: AGREEMENT_TERMS_PARAMS.interactionMode,
+    conversationAllowance: AGREEMENT_TERMS_PARAMS.conversationAllowance,
+    description: 'string',
+    sources: AGREEMENT_TERMS_PARAMS.sources,
+}, handlerFor('agreement_counter'), { description: 'Counter a pending proposal with revised terms instead of approving or rejecting. Check status first with agreement_get.' });
 export const agreementGetTool = defineTool('agreement_get', { agreementId: { type: 'string', required: true } }, handlerFor('agreement_get'), { description: 'Read the current proposal status for an agreement (pending, approved, rejected, countered, expired).' });
 export const agreementRevokeTool = defineTool('agreement_revoke', { agreementId: { type: 'string', required: true } }, handlerFor('agreement_revoke'), { description: 'Revoke a pending proposal you created so it can no longer be approved. Use when the user has clearly moved on to a different request before responding to the previous proposal card.' });
 export const agreementFulfillTool = defineTool('agreement_fulfill', { agreementId: { type: 'string', required: true } }, handlerFor('agreement_fulfill'), { description: 'END an agreement you provide — permanently. Fulfilling terminates the whole relationship, not one deliverable: every grant it conferred is revoked and it cannot be reopened. Linked chats remain independent rooms governed by their own grants. Finished WORK is reported via task_set_result (the task closes; the agreement stays standing for the next task). Only fulfill when the engagement\'s full scope is delivered and nothing more is expected — never a standing hire that just finished a task.' });

package/dist/runtime/agreementContext.js

@@ -49,7 +49,10 @@ export async function withAgreementContext(event, read) {
                         relationship: agreement.engagementKind === 'link',
                         interactionMode: terms.interactionMode ?? 'both',
                         parentAgreementId: agreement.parentAgreementId ?? null,
-                        allowanceScope: terms.conversationAllowanceScope ?? 'direct',
+                        allowanceScope: (money.paymentStatus === 'included' || money.paymentStatus === 'allocated') &&
+                            agreement.parentAgreementId
+                            ? 'job'
+                            : 'own',
                         scope: terms.description,
                         lifecycle: terms.lifecycle,
                         expiresAt: terms.expiresAt ?? null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.38.15",
+  "version": "0.38.16",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "homepage": "https://ziggsai.com/docs",
   "bugs": {
@@ -30,7 +30,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.284",
     "@anthropic-ai/sdk": "^0.110.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "0.37.18",
+    "@ziggs-ai/api-client": "0.37.19",
     "@ziggs-ai/contracts": "^0.23.3",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",