@openwop/openwop 1.1.2 → 1.1.5

package/dist/index.d.ts

@@ -12,10 +12,10 @@
 export { OpenwopClient } from './client.js';
 export type { OpenwopClientOptions, MutationOptions } from './client.js';
 export { WopError } from './types.js';
-export type { AuditVerifyAnomaly, AuditVerifyCheckpoint, AuditVerifyResult, BulkCancelRunResult, BulkCancelRunsRequest, BulkCancelRunsResponse, Capabilities, CancelRunRequest, CancelRunResponse, CreateRunRequest, CreateRunResponse, ErrorEnvelope, ForkRunRequest, ForkRunResponse, DebugBundle, DebugBundleOptions, RegisterWebhookRequest, RegisterWebhookResponse, InterruptByTokenInspection, PauseRunRequest, PauseRunResponse, PollEventsResponse, ResolveInterruptByTokenResponse, ResolveInterruptRequest, ResolveInterruptResponse, ResumeRunRequest, ResumeRunResponse, RunConfigurable, RunEventDoc, RunSnapshot, RunStatus, StreamMode, TypedRunEvent, AgentReasonedPayload, AgentReasoningDeltaPayload, AgentToolCalledPayload, AgentToolReturnedPayload, AgentHandoffPayload, AgentDecidedPayload, GetPromptRequest, ListPromptsRequest, ListPromptsResponse, PromptKind, PromptRef, PromptTemplate, PromptVariable, RenderPromptRequest, RenderPromptResponse, } from './types.js';
+export type { AuditVerifyAnomaly, AuditVerifyCheckpoint, AuditVerifyResult, BulkCancelRunResult, BulkCancelRunsRequest, BulkCancelRunsResponse, Capabilities, CancelRunRequest, CancelRunResponse, CreateRunRequest, CreateRunResponse, ErrorEnvelope, ForkRunRequest, ForkRunResponse, DebugBundle, DebugBundleOptions, RegisterWebhookRequest, RegisterWebhookResponse, InterruptByTokenInspection, PauseRunRequest, PauseRunResponse, PollEventsResponse, ResolveInterruptByTokenResponse, ResolveInterruptRequest, ResolveInterruptResponse, ResumeRunRequest, ResumeRunResponse, RunConfigurable, RunDiffEventDiff, RunDiffResponse, RunEventDoc, RunSnapshot, RunStatus, StreamMode, TypedRunEvent, WorkspaceFile, PutWorkspaceFileRequest, AgentReasonedPayload, AgentReasoningDeltaPayload, AgentToolCalledPayload, AgentToolReturnedPayload, AgentHandoffPayload, AgentDecidedPayload, MemoryWrittenPayload, GetPromptRequest, ListPromptsRequest, ListPromptsResponse, PromptKind, PromptRef, PromptTemplate, PromptVariable, RenderPromptRequest, RenderPromptResponse, } from './types.js';
 export { streamEvents } from './sse.js';
 export type { EventsStreamContext, EventsStreamOptions } from './sse.js';
-export { isAgentReasoned, isAgentReasoningDelta, isAgentToolCalled, isAgentToolReturned, isAgentHandoff, isAgentDecided, subscribeToAgentReasoning, } from './event-helpers.js';
+export { isAgentReasoned, isAgentReasoningDelta, isAgentToolCalled, isAgentToolReturned, isAgentHandoff, isAgentDecided, isMemoryWritten, subscribeToAgentReasoning, } from './event-helpers.js';
 export type { AgentReasoningCallbacks, Unsubscribe, } from './event-helpers.js';
 export { ACTIVE_RUN_STATUSES, TERMINAL_RUN_STATUSES, isTerminalRunStatus, HTTP_ERROR_CODES, isHttpErrorCode, RUN_ERROR_CODES, isRunErrorCode, } from './run-helpers.js';
 export type { ActiveRunStatus, TerminalRunStatus, HttpErrorCode, RunErrorCode, RunError, } from './run-helpers.js';
@@ -26,4 +26,8 @@ export type { VerifyWebhookSignatureOptions, VerifyWebhookOutcome, } from './web
 export { RegistryClient } from './registry-helpers.js';
 export type { RegistryClientOptions, RegistryDiscovery, RegistryIndex, RegistryIndexEntry, RegistryPackMetadata, RegistryVersionManifest, } from './registry-helpers.js';
 export type { AIEnvelope, AIEnvelopeErrorPayload, ClarificationRequestPayload, EnvelopeContract, EnvelopeContractRefusal, EnvelopeContractsCapability, EnvelopeMeta, EnvelopeOutcome, EnvelopeStrictness, PartialInfo, SchemaRequestPayload, SchemaResponsePayload, ValidationDetail, } from './types.js';
+export { buildReasoningDirective } from './envelope-directive.js';
+export type { ReasoningDirectiveStrength } from './envelope-directive.js';
+export { parseRefusal } from './parse-refusal.js';
+export type { RefusalProvider, RefusalSignal } from './parse-refusal.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,0BAA0B,EAC1B,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,+BAA+B,EAC/B,uBAAuB,EACvB,wBAAwB,EACxB,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,WAAW,EACX,WAAW,EACX,SAAS,EACT,UAAU,EACV,aAAa,EACb,oBAAoB,EACpB,0BAA0B,EAC1B,sBAAsB,EACtB,wBAAwB,EACxB,mBAAmB,EACnB,mBAAmB,EAEnB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,UAAU,EACV,SAAS,EACT,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAIzE,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,cAAc,EACd,yBAAyB,GAC1B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,uBAAuB,EACvB,WAAW,GACZ,MAAM,oBAAoB,CAAC;AAK5B,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,QAAQ,GACT,MAAM,kBAAkB,CAAC;AAM1B,OAAO,EACL,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAMtE,OAAO,EACL,wCAAwC,EACxC,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,6BAA6B,EAC7B,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EACV,qBAAqB,EACrB,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,uBAAuB,CAAC;AAI/B,YAAY,EACV,UAAU,EACV,sBAAsB,EACtB,2BAA2B,EAC3B,gBAAgB,EAChB,uBAAuB,EACvB,2BAA2B,EAC3B,YAAY,EACZ,eAAe,EACf,kBAAkB,EAClB,WAAW,EACX,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -14,7 +14,7 @@ export { WopError } from './types.js';
 export { streamEvents } from './sse.js';
 // RFC 0002 + RFC 0024 typed event helpers — type guards over `RunEventDoc`
 // plus a high-level streaming-reasoning subscription helper.
-export { isAgentReasoned, isAgentReasoningDelta, isAgentToolCalled, isAgentToolReturned, isAgentHandoff, isAgentDecided, subscribeToAgentReasoning, } from './event-helpers.js';
+export { isAgentReasoned, isAgentReasoningDelta, isAgentToolCalled, isAgentToolReturned, isAgentHandoff, isAgentDecided, isMemoryWritten, subscribeToAgentReasoning, } from './event-helpers.js';
 // Run-status + run-error helpers (added in 1). Forward-compat predicates
 // over the wire-format unions declared above; full design + rationale in
 // `run-helpers.ts`.
@@ -33,4 +33,21 @@ export { DEFAULT_WEBHOOK_FRESHNESS_WINDOW_SECONDS, verifyWebhookSignature, signW
 // typed client for the public node-pack registry at packs.openwop.dev
 // per spec/v1/registry-operations.md.
 export { RegistryClient } from './registry-helpers.js';
+// RFC 0030 §A `reasoning` field prompt-directive helper. Hosts that
+// advertise `capabilities.envelopes.reasoning.supported: true` use this
+// to synthesize the system-prompt fragment that instructs the model to
+// populate the OPTIONAL `reasoning` field. See `envelope-directive.ts`
+// for the operational note on `"mandatory"` strength (provider-side
+// refusal risk per the 2026-05-21 RFC 0030 amendment).
+export { buildReasoningDirective } from './envelope-directive.js';
+// RFC 0032 §B.3 + RFC 0033 §D refusal detection helper. Normalizes
+// per-provider safety-stop signals (Anthropic `stop_reason: "refusal"`,
+// OpenAI `message.refusal` + `finish_reason: "content_filter"`, Gemini
+// `finishReason: "SAFETY"` + `promptFeedback.blockReason: "SAFETY"`)
+// to a canonical `{ refusalText, safetyCategory?, provider }` shape.
+// Hosts route the non-null return through `envelope.refusal` emission
+// + the `envelope_refusal` terminal error code (RFC 0033 §F).
+// **SECURITY:** Pass `refusalText` through the BYOK redaction harness
+// BEFORE persistence — this helper does NOT redact.
+export { parseRefusal } from './parse-refusal.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAoDtC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGxC,2EAA2E;AAC3E,6DAA6D;AAC7D,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,cAAc,EACd,yBAAyB,GAC1B,MAAM,oBAAoB,CAAC;AAM5B,yEAAyE;AACzE,yEAAyE;AACzE,oBAAoB;AACpB,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,cAAc,GACf,MAAM,kBAAkB,CAAC;AAS1B,iDAAiD;AACjD,sEAAsE;AACtE,mEAAmE;AACnE,uDAAuD;AACvD,OAAO,EACL,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAG/B,sEAAsE;AACtE,4DAA4D;AAC5D,sEAAsE;AACtE,uDAAuD;AACvD,OAAO,EACL,wCAAwC,EACxC,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAM9B,uEAAuE;AACvE,sEAAsE;AACtE,sCAAsC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AA0DtC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGxC,2EAA2E;AAC3E,6DAA6D;AAC7D,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,cAAc,EACd,eAAe,EACf,yBAAyB,GAC1B,MAAM,oBAAoB,CAAC;AAM5B,yEAAyE;AACzE,yEAAyE;AACzE,oBAAoB;AACpB,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,cAAc,GACf,MAAM,kBAAkB,CAAC;AAS1B,iDAAiD;AACjD,sEAAsE;AACtE,mEAAmE;AACnE,uDAAuD;AACvD,OAAO,EACL,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAG/B,sEAAsE;AACtE,4DAA4D;AAC5D,sEAAsE;AACtE,uDAAuD;AACvD,OAAO,EACL,wCAAwC,EACxC,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAM9B,uEAAuE;AACvE,sEAAsE;AACtE,sCAAsC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AA4BvD,oEAAoE;AACpE,wEAAwE;AACxE,uEAAuE;AACvE,uEAAuE;AACvE,oEAAoE;AACpE,uDAAuD;AACvD,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAGlE,mEAAmE;AACnE,wEAAwE;AACxE,uEAAuE;AACvE,qEAAqE;AACrE,qEAAqE;AACrE,sEAAsE;AACtE,8DAA8D;AAC9D,sEAAsE;AACtE,oDAAoD;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/parse-refusal.d.ts

@@ -0,0 +1,114 @@
+/**
+ * parseRefusal — normalize per-provider LLM safety-stop signals to the
+ * canonical RFC 0032 §B.3 refusal shape.
+ *
+ * The three Tier-1 vendors (Anthropic / OpenAI / Google Gemini) surface
+ * refusals through different fields:
+ *
+ *   - **Anthropic Messages API**: `stop_reason: "refusal"` (their 2025
+ *     release) OR `stop_reason: "end_turn"` accompanied by safety-stop
+ *     markers in the content. Refusal text MAY be inline in the
+ *     `content[]` array's text blocks.
+ *   - **OpenAI Chat Completions**: `choices[0].finish_reason:
+ *     "content_filter"` OR `choices[0].message.refusal: <string>` (the
+ *     refusal-text field added in their structured-output release).
+ *   - **Google Gemini**: `candidates[0].finishReason: "SAFETY"` OR
+ *     `promptFeedback.blockReason: "SAFETY"` (input-side block).
+ *
+ * Without normalization, every host re-implements this detection. This
+ * helper consolidates the per-vendor shape-detection and returns a
+ * canonical `RefusalSignal | null` — null when the response is a
+ * normal completion (no refusal detected).
+ *
+ * Per RFC 0032 §B.3 + RFC 0033 §D, hosts MUST NOT retry on refusal
+ * (circumvention concern). Callers route the non-null return through
+ * `envelope.refusal` emission + the `envelope_refusal` terminal error
+ * code (per RFC 0033 §F).
+ *
+ * Per SECURITY/invariants.yaml §envelope-refusal-no-prompt-leak,
+ * `refusalText` MUST be passed through the host's BYOK redaction
+ * harness BEFORE persistence — this helper does NOT redact; the
+ * caller is responsible for SR-1 carry-forward.
+ *
+ * @see RFCS/0032-envelope-reliability-events.md §B.3
+ * @see RFCS/0033-envelope-completion-contract.md §D + §F
+ * @see SECURITY/invariants.yaml §envelope-refusal-no-prompt-leak
+ */
+/**
+ * Provider identifier for the matched shape. `"unknown"` is reserved
+ * for refusals matched on heuristic signals without a definitive
+ * vendor-shape match.
+ */
+export type RefusalProvider = 'anthropic' | 'openai' | 'google' | 'unknown';
+/**
+ * Canonical refusal signal. All three Tier-1 vendor shapes normalize
+ * to this form. `null` from `parseRefusal()` means "no refusal detected"
+ * (a normal completion); a non-null `RefusalSignal` means the caller
+ * SHOULD route through the RFC 0032 §B.3 refusal-emission path.
+ */
+export interface RefusalSignal {
+    /**
+     * The provider's refusal text, when surfaced. MAY be `null` even for
+     * detected refusals — Anthropic + Gemini frequently refuse without
+     * inline text (the safety filter is opaque to the model). OpenAI's
+     * `message.refusal` field is the most consistent source of human-
+     * readable refusal text.
+     *
+     * **SECURITY:** When non-null, `refusalText` MAY contain prompt
+     * content that triggered the safety filter. Callers MUST pass it
+     * through their BYOK + prompt-content redaction harness BEFORE
+     * persistence (per `envelope-refusal-no-prompt-leak` SECURITY
+     * invariant).
+     */
+    refusalText: string | null;
+    /**
+     * Provider-specific safety-category identifier, when surfaced.
+     * Examples: Gemini's safety-rating categories
+     * (`HARM_CATEGORY_HARASSMENT`, etc.), OpenAI's content-filter category,
+     * Anthropic's policy-violation tag. Hosts MAY echo this on the
+     * `envelope.refusal.safetyCategory` event field for downstream
+     * observability.
+     */
+    safetyCategory?: string;
+    /**
+     * Which provider's shape was matched. Useful for debugging
+     * cross-host integration + for hosts that want to route refusals
+     * differently per vendor (e.g., different operator notifications).
+     */
+    provider: RefusalProvider;
+}
+/**
+ * Parse a provider response into a canonical refusal signal.
+ *
+ * Returns `null` when no refusal is detected (normal completion).
+ * Returns a `RefusalSignal` when the response matches one of the
+ * three Tier-1 vendors' safety-stop shapes.
+ *
+ * Detection order: OpenAI → Anthropic → Gemini. Each detector inspects
+ * a distinctive top-level field, so cross-vendor false-positives are
+ * unlikely. A response that doesn't match any vendor shape returns
+ * `null` (hosts that route through novel providers add their own
+ * detector + fall back to this for the three known ones).
+ *
+ * @example
+ * ```ts
+ * import { parseRefusal } from '@openwop/openwop';
+ *
+ * const response = await callOpenAI({...});
+ * const refusal = parseRefusal(response);
+ * if (refusal) {
+ *   // Route through envelope.refusal emission + envelope_refusal error code.
+ *   // REMEMBER to redact refusalText through the BYOK harness before
+ *   // persistence (SECURITY invariant envelope-refusal-no-prompt-leak).
+ *   await emitEnvelopeRefusal({
+ *     refusalText: redactBYOK(refusal.refusalText),
+ *     safetyCategory: refusal.safetyCategory,
+ *     provider: refusal.provider,
+ *   });
+ *   throw new EnvelopeRefusalError(...);
+ * }
+ * // ...normal-completion handling...
+ * ```
+ */
+export declare function parseRefusal(providerResponse: unknown): RefusalSignal | null;
+//# sourceMappingURL=parse-refusal.d.ts.map

package/dist/parse-refusal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-refusal.d.ts","sourceRoot":"","sources":["../src/parse-refusal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE5E;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;;OAYG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAE3B;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,QAAQ,EAAE,eAAe,CAAC;CAC3B;AA6LD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,YAAY,CAAC,gBAAgB,EAAE,OAAO,GAAG,aAAa,GAAG,IAAI,CAM5E"}

package/dist/parse-refusal.js

@@ -0,0 +1,216 @@
+/**
+ * parseRefusal — normalize per-provider LLM safety-stop signals to the
+ * canonical RFC 0032 §B.3 refusal shape.
+ *
+ * The three Tier-1 vendors (Anthropic / OpenAI / Google Gemini) surface
+ * refusals through different fields:
+ *
+ *   - **Anthropic Messages API**: `stop_reason: "refusal"` (their 2025
+ *     release) OR `stop_reason: "end_turn"` accompanied by safety-stop
+ *     markers in the content. Refusal text MAY be inline in the
+ *     `content[]` array's text blocks.
+ *   - **OpenAI Chat Completions**: `choices[0].finish_reason:
+ *     "content_filter"` OR `choices[0].message.refusal: <string>` (the
+ *     refusal-text field added in their structured-output release).
+ *   - **Google Gemini**: `candidates[0].finishReason: "SAFETY"` OR
+ *     `promptFeedback.blockReason: "SAFETY"` (input-side block).
+ *
+ * Without normalization, every host re-implements this detection. This
+ * helper consolidates the per-vendor shape-detection and returns a
+ * canonical `RefusalSignal | null` — null when the response is a
+ * normal completion (no refusal detected).
+ *
+ * Per RFC 0032 §B.3 + RFC 0033 §D, hosts MUST NOT retry on refusal
+ * (circumvention concern). Callers route the non-null return through
+ * `envelope.refusal` emission + the `envelope_refusal` terminal error
+ * code (per RFC 0033 §F).
+ *
+ * Per SECURITY/invariants.yaml §envelope-refusal-no-prompt-leak,
+ * `refusalText` MUST be passed through the host's BYOK redaction
+ * harness BEFORE persistence — this helper does NOT redact; the
+ * caller is responsible for SR-1 carry-forward.
+ *
+ * @see RFCS/0032-envelope-reliability-events.md §B.3
+ * @see RFCS/0033-envelope-completion-contract.md §D + §F
+ * @see SECURITY/invariants.yaml §envelope-refusal-no-prompt-leak
+ */
+/**
+ * Try to parse the response as OpenAI Chat Completions output.
+ *
+ * Detection: top-level `choices` array. Refusal signals:
+ *   - `choices[0].finish_reason === "content_filter"`
+ *   - `choices[0].message.refusal` is a non-empty string
+ */
+function tryParseOpenAI(response) {
+    if (!response || typeof response !== 'object')
+        return null;
+    const r = response;
+    if (!Array.isArray(r.choices) || r.choices.length === 0)
+        return null;
+    const choice = r.choices[0];
+    if (!choice || typeof choice !== 'object')
+        return null;
+    const finishReason = choice.finish_reason;
+    const message = choice.message;
+    const refusalField = message && typeof message === 'object' ? message.refusal : undefined;
+    // Primary signal: explicit refusal-text field. OpenAI's structured-output
+    // release populates this when the safety filter intervenes.
+    if (typeof refusalField === 'string' && refusalField.length > 0) {
+        return { refusalText: refusalField, provider: 'openai' };
+    }
+    // Secondary signal: finish_reason. content_filter is the canonical
+    // safety-stop value.
+    if (finishReason === 'content_filter') {
+        const text = message && typeof message === 'object' && typeof message.content === 'string'
+            ? message.content
+            : null;
+        return { refusalText: text, safetyCategory: 'content_filter', provider: 'openai' };
+    }
+    return null;
+}
+/**
+ * Try to parse the response as Anthropic Messages API output.
+ *
+ * Detection: top-level `stop_reason` field (Anthropic's distinctive
+ * marker). Refusal signals:
+ *   - `stop_reason === "refusal"` (their 2025 release)
+ *
+ * Anthropic does not surface a distinct safety-category field on
+ * refusals; the `refusal` stop_reason is the binary signal.
+ */
+function tryParseAnthropic(response) {
+    if (!response || typeof response !== 'object')
+        return null;
+    const r = response;
+    if (typeof r.stop_reason !== 'string')
+        return null;
+    if (r.stop_reason === 'refusal') {
+        // Extract refusal text from the content array (Anthropic returns an
+        // array of typed blocks; refusal text appears in `text`-type blocks).
+        let refusalText = null;
+        if (Array.isArray(r.content)) {
+            const textBlocks = [];
+            for (const block of r.content) {
+                if (block && typeof block === 'object') {
+                    const b = block;
+                    if (b.type === 'text' && typeof b.text === 'string') {
+                        textBlocks.push(b.text);
+                    }
+                }
+            }
+            if (textBlocks.length > 0)
+                refusalText = textBlocks.join('\n');
+        }
+        return { refusalText, provider: 'anthropic' };
+    }
+    return null;
+}
+/**
+ * Try to parse the response as Google Gemini `generateContent` output.
+ *
+ * Detection: top-level `candidates` array OR top-level `promptFeedback`
+ * object. Refusal signals:
+ *   - `candidates[0].finishReason === "SAFETY"` (output-side block)
+ *   - `promptFeedback.blockReason === "SAFETY"` (input-side block)
+ *
+ * Gemini surfaces safety categories on `safetyRatings[]`; this helper
+ * picks the highest-probability HIGH/MEDIUM-tier category as
+ * `safetyCategory` when available.
+ */
+function tryParseGemini(response) {
+    if (!response || typeof response !== 'object')
+        return null;
+    const r = response;
+    // Output-side safety block.
+    if (Array.isArray(r.candidates) && r.candidates.length > 0) {
+        const candidate = r.candidates[0];
+        if (candidate && typeof candidate === 'object' && candidate.finishReason === 'SAFETY') {
+            const safetyCategory = extractGeminiHighestRiskCategory(candidate.safetyRatings);
+            const result = { refusalText: null, provider: 'google' };
+            if (safetyCategory !== undefined)
+                result.safetyCategory = safetyCategory;
+            return result;
+        }
+    }
+    // Input-side safety block (Gemini rejected the prompt itself).
+    if (r.promptFeedback && typeof r.promptFeedback === 'object') {
+        const pf = r.promptFeedback;
+        if (typeof pf.blockReason === 'string' && pf.blockReason.toUpperCase().includes('SAFETY')) {
+            const safetyCategory = extractGeminiHighestRiskCategory(pf.safetyRatings);
+            const result = { refusalText: null, provider: 'google' };
+            if (safetyCategory !== undefined)
+                result.safetyCategory = safetyCategory;
+            return result;
+        }
+    }
+    return null;
+}
+/**
+ * From a Gemini `safetyRatings[]` array, return the highest-probability
+ * non-NEGLIGIBLE category identifier. Returns `undefined` when the
+ * array is absent or all ratings are NEGLIGIBLE.
+ */
+function extractGeminiHighestRiskCategory(safetyRatings) {
+    if (!Array.isArray(safetyRatings))
+        return undefined;
+    const PROBABILITY_RANK = {
+        HIGH: 3,
+        MEDIUM: 2,
+        LOW: 1,
+        NEGLIGIBLE: 0,
+    };
+    let best = null;
+    for (const rating of safetyRatings) {
+        if (!rating || typeof rating !== 'object')
+            continue;
+        const r = rating;
+        if (typeof r.category !== 'string' || typeof r.probability !== 'string')
+            continue;
+        const rank = PROBABILITY_RANK[r.probability.toUpperCase()] ?? 0;
+        if (rank === 0)
+            continue;
+        if (best === null || rank > best.rank) {
+            best = { category: r.category, rank };
+        }
+    }
+    return best?.category;
+}
+/**
+ * Parse a provider response into a canonical refusal signal.
+ *
+ * Returns `null` when no refusal is detected (normal completion).
+ * Returns a `RefusalSignal` when the response matches one of the
+ * three Tier-1 vendors' safety-stop shapes.
+ *
+ * Detection order: OpenAI → Anthropic → Gemini. Each detector inspects
+ * a distinctive top-level field, so cross-vendor false-positives are
+ * unlikely. A response that doesn't match any vendor shape returns
+ * `null` (hosts that route through novel providers add their own
+ * detector + fall back to this for the three known ones).
+ *
+ * @example
+ * ```ts
+ * import { parseRefusal } from '@openwop/openwop';
+ *
+ * const response = await callOpenAI({...});
+ * const refusal = parseRefusal(response);
+ * if (refusal) {
+ *   // Route through envelope.refusal emission + envelope_refusal error code.
+ *   // REMEMBER to redact refusalText through the BYOK harness before
+ *   // persistence (SECURITY invariant envelope-refusal-no-prompt-leak).
+ *   await emitEnvelopeRefusal({
+ *     refusalText: redactBYOK(refusal.refusalText),
+ *     safetyCategory: refusal.safetyCategory,
+ *     provider: refusal.provider,
+ *   });
+ *   throw new EnvelopeRefusalError(...);
+ * }
+ * // ...normal-completion handling...
+ * ```
+ */
+export function parseRefusal(providerResponse) {
+    return (tryParseOpenAI(providerResponse) ??
+        tryParseAnthropic(providerResponse) ??
+        tryParseGemini(providerResponse));
+}
+//# sourceMappingURL=parse-refusal.js.map

package/dist/parse-refusal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-refusal.js","sourceRoot":"","sources":["../src/parse-refusal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AA8FH;;;;;;GAMG;AACH,SAAS,cAAc,CAAC,QAAiB;IACvC,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3D,MAAM,CAAC,GAAG,QAA0B,CAAC;IACrC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACrE,MAAM,MAAM,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAiB,CAAC;IAC5C,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAEvD,MAAM,YAAY,GAAG,MAAM,CAAC,aAAa,CAAC;IAC1C,MAAM,OAAO,GAAG,MAAM,CAAC,OAA0C,CAAC;IAClE,MAAM,YAAY,GAAG,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IAE1F,0EAA0E;IAC1E,4DAA4D;IAC5D,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;IAC3D,CAAC;IAED,mEAAmE;IACnE,qBAAqB;IACrB,IAAI,YAAY,KAAK,gBAAgB,EAAE,CAAC;QACtC,MAAM,IAAI,GACR,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ;YAC3E,CAAC,CAAC,OAAO,CAAC,OAAO;YACjB,CAAC,CAAC,IAAI,CAAC;QACX,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,cAAc,EAAE,gBAAgB,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;IACrF,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,iBAAiB,CAAC,QAAiB;IAC1C,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3D,MAAM,CAAC,GAAG,QAA6B,CAAC;IACxC,IAAI,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAEnD,IAAI,CAAC,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QAChC,oEAAoE;QACpE,sEAAsE;QACtE,IAAI,WAAW,GAAkB,IAAI,CAAC;QACtC,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;YAC7B,MAAM,UAAU,GAAa,EAAE,CAAC;YAChC,KAAK,MAAM,KAAK,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;gBAC9B,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;oBACvC,MAAM,CAAC,GAAG,KAA2B,CAAC;oBACtC,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;wBACpD,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;oBAC1B,CAAC;gBACH,CAAC;YACH,CAAC;YACD,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC;gBAAE,WAAW,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjE,CAAC;QACD,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;IAChD,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,cAAc,CAAC,QAAiB;IACvC,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3D,MAAM,CAAC,GAAG,QAA0B,CAAC;IAErC,4BAA4B;IAC5B,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3D,MAAM,SAAS,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAoB,CAAC;QACrD,IAAI,SAAS,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,CAAC,YAAY,KAAK,QAAQ,EAAE,CAAC;YACtF,MAAM,cAAc,GAAG,gCAAgC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC;YACjF,MAAM,MAAM,GAAkB,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;YACxE,IAAI,cAAc,KAAK,SAAS;gBAAE,MAAM,CAAC,cAAc,GAAG,cAAc,CAAC;YACzE,OAAO,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IAED,+DAA+D;IAC/D,IAAI,CAAC,CAAC,cAAc,IAAI,OAAO,CAAC,CAAC,cAAc,KAAK,QAAQ,EAAE,CAAC;QAC7D,MAAM,EAAE,GAAG,CAAC,CAAC,cAAsC,CAAC;QACpD,IAAI,OAAO,EAAE,CAAC,WAAW,KAAK,QAAQ,IAAI,EAAE,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1F,MAAM,cAAc,GAAG,gCAAgC,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC;YAC1E,MAAM,MAAM,GAAkB,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;YACxE,IAAI,cAAc,KAAK,SAAS;gBAAE,MAAM,CAAC,cAAc,GAAG,cAAc,CAAC;YACzE,OAAO,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,SAAS,gCAAgC,CAAC,aAAsB;IAC9D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC;QAAE,OAAO,SAAS,CAAC;IACpD,MAAM,gBAAgB,GAA2B;QAC/C,IAAI,EAAE,CAAC;QACP,MAAM,EAAE,CAAC;QACT,GAAG,EAAE,CAAC;QACN,UAAU,EAAE,CAAC;KACd,CAAC;IACF,IAAI,IAAI,GAA8C,IAAI,CAAC;IAC3D,KAAK,MAAM,MAAM,IAAI,aAAa,EAAE,CAAC;QACnC,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,SAAS;QACpD,MAAM,CAAC,GAAG,MAA4B,CAAC;QACvC,IAAI,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ;YAAE,SAAS;QAClF,MAAM,IAAI,GAAG,gBAAgB,CAAC,CAAC,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,CAAC;QAChE,IAAI,IAAI,KAAK,CAAC;YAAE,SAAS;QACzB,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;YACtC,IAAI,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC;QACxC,CAAC;IACH,CAAC;IACD,OAAO,IAAI,EAAE,QAAQ,CAAC;AACxB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,YAAY,CAAC,gBAAyB;IACpD,OAAO,CACL,cAAc,CAAC,gBAAgB,CAAC;QAChC,iBAAiB,CAAC,gBAAgB,CAAC;QACnC,cAAc,CAAC,gBAAgB,CAAC,CACjC,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -21,6 +21,10 @@ export interface Capabilities {
         schemaRounds: number;
         envelopesPerTurn: number;
         maxNodeExecutions?: number;
+        /** RFC 0058. Engine-side wall-clock ceiling per run (ms); upper bound for `RunConfigurable.runTimeoutMs`. */
+        maxRunDurationMs?: number;
+        /** RFC 0058. Engine-side agent-loop iteration ceiling; upper bound for `RunConfigurable.maxLoopIterations`. */
+        maxLoopIterations?: number;
     };
     extensions?: Record<string, unknown>;
     implementation?: {
@@ -35,6 +39,12 @@ export interface Capabilities {
     observability?: Record<string, unknown>;
     minClientVersion?: string;
 }
+/**
+ * The `kind` discriminator on a `cap.breached` event payload
+ * (`run-event-payloads.schema.json#capBreached`). The four engine kinds, the
+ * RFC 0008 §K `wasm-*` runtime caps, and the RFC 0058 run-scoped bounds.
+ */
+export type CapBreachedKind = 'clarification' | 'schema' | 'envelopes' | 'node-executions' | 'wasm-memory' | 'wasm-fuel' | 'wasm-execution-time' | 'run-duration' | 'loop-iterations';
 export interface RunSnapshot {
     runId: string;
     workflowId: string;
@@ -76,6 +86,15 @@ export interface RunSnapshot {
 export interface RunConfigurable {
     /** Override the per-run node-execution ceiling. Clamped server-side. */
     recursionLimit?: number;
+    /** RFC 0058. Wall-clock run deadline (ms from `run.started`); clamped to
+     *  `Capabilities.limits.maxRunDurationMs`. Breach → `cap.breached
+     *  { kind: 'run-duration' }` + `run_timeout`. */
+    runTimeoutMs?: number;
+    /** RFC 0058. Agent-loop iteration ceiling (one per orchestrator turn);
+     *  clamped to `Capabilities.limits.maxLoopIterations`. Breach →
+     *  `cap.breached { kind: 'loop-iterations' }` + `loop_limit_exceeded`.
+     *  Ignored unless the host advertises `capabilities.agents.loop.supported`. */
+    maxLoopIterations?: number;
     /** Override AI model for nodes that consume `ctx.config.configurable.model`. */
     model?: string;
     /** Override AI temperature (server SHOULD enforce 0..2). */
@@ -229,6 +248,107 @@ export interface ForkRunResponse {
     status: RunStatus;
     eventsUrl: string;
 }
+/** RFC 0056 — a non-blocking quality signal on a run/event/node. */
+export type AnnotationSignal = {
+    kind: 'rating';
+    rating: number;
+} | {
+    kind: 'flag';
+} | {
+    kind: 'label';
+    label: string;
+} | {
+    kind: 'correction';
+    correction: string;
+};
+/** RFC 0056 persisted annotation (`annotation.schema.json`). A side-resource —
+ *  not a replayable run-event-log entry. */
+export interface Annotation {
+    annotationId: string;
+    target: {
+        runId: string;
+        eventId?: string;
+        nodeId?: string;
+    };
+    signal: AnnotationSignal;
+    actor: {
+        principalRef: string;
+    };
+    note?: string;
+    createdAt: string;
+}
+/** RFC 0056 request body for `createAnnotation` (`annotation-create.schema.json`).
+ *  The host assigns `annotationId`/`createdAt`/`actor` and binds `target.runId`. */
+export interface CreateAnnotationRequest {
+    target?: {
+        eventId?: string;
+        nodeId?: string;
+    };
+    signal: AnnotationSignal;
+    note?: string;
+}
+/** RFC 0059 versioned, tenant·workspace-scoped ground-truth file
+ *  (`workspace-file.schema.json`). The `list` endpoint returns this shape
+ *  minus `content` (metadata only). */
+export interface WorkspaceFile {
+    path: string;
+    content: string;
+    contentType?: string;
+    version: number;
+    etag?: string;
+    updatedAt: string;
+}
+/** RFC 0059 request body for `putWorkspaceFile` (`workspace-file-create.schema.json`).
+ *  `path` is URL-bound; the host assigns `version`/`etag`/`updatedAt`.
+ *  Optimistic concurrency is expressed via the `If-Match` header, not the body. */
+export interface PutWorkspaceFileRequest {
+    content: string;
+    contentType?: string;
+}
+/**
+ * Response from `GET /v1/runs/{runId}/ancestry` — RFC 0040 §C cross-host
+ * composition parent. `parent: null` for top-level runs (not dispatched
+ * from any other run); otherwise `parent.wellKnownUrl` is set when the
+ * parent is on a different host so callers can walk the chain.
+ *
+ * Capability-gated: hosts not advertising
+ * `capabilities.multiAgent.executionModel.crossHostCausation.ancestryEndpointSupported: true`
+ * return 404; the SDK surfaces that as `null` via `runs.ancestry()`.
+ */
+export interface RunAncestryResponse {
+    runId: string;
+    hostId: string;
+    parent: null | {
+        runId: string;
+        hostId: string;
+        wellKnownUrl?: string;
+        cause: 'mcp-tool-call' | 'a2a-message' | 'core.subWorkflow' | 'core.dispatch';
+    };
+}
+/** RFC 0054 — response from `GET /v1/runs/{runId}:diff?against={otherRunId}`.
+ *  Mirror of `run-diff-response.schema.json`. Deterministic, replay-aware
+ *  structured diff of two runs' event sequences + terminal states. */
+export interface RunDiffEventDiff {
+    seq: number;
+    op: 'added' | 'removed' | 'changed';
+    /** Present unless `op === 'added'`. */
+    aEvent?: RunEventDoc;
+    /** Present unless `op === 'removed'`. */
+    bEvent?: RunEventDoc;
+}
+export interface RunDiffResponse {
+    /** The `{runId}` run. */
+    a: string;
+    /** The `against` run. */
+    b: string;
+    /** Sequence at which the logs first diverge; null if identical. */
+    divergedAtSeq: number | null;
+    eventDiffs: RunDiffEventDiff[];
+    /** Diff of terminal RunSnapshot states (redaction-safe). */
+    stateDiff: Record<string, unknown>;
+    /** True if either run was in-flight and only a prefix was compared. */
+    truncated?: boolean;
+}
 export interface ResolveInterruptRequest {
     resumeValue: unknown;
 }
@@ -487,6 +607,18 @@ export interface AgentDecidedPayload {
     confidence?: number;
     [key: string]: unknown;
 }
+/** `memory.written` payload (RFC 0057). Content-free per-write attribution:
+ *  identifiers + non-secret tags only — never the entry content (the read
+ *  side serves that, already SR-1-redacted). `nodeId` is omitted for host
+ *  session-end writes with no node attribution. */
+export interface MemoryWrittenPayload {
+    memoryRef: string;
+    memoryId: string;
+    nodeId?: string;
+    agentId?: string;
+    tags?: string[];
+    [key: string]: unknown;
+}
 /** A `RunEventDoc` narrowed to a specific event-type discriminator +
  *  payload shape. Returned by the `isAgent*` type guards in
  *  `event-helpers.ts`. */
@@ -736,4 +868,33 @@ export declare class WopError extends Error {
     readonly traceId: string | undefined;
     constructor(status: number, rawText: string, envelope: ErrorEnvelope | undefined, traceparent: string | undefined);
 }
+/**
+ * One installed manifest agent, as projected by `GET /v1/agents` /
+ * `GET /v1/agents/{agentId}` (RFC 0072 §A). Read-only — never carries the
+ * system-prompt body, resolved handoff schemas, or credential material (SR-1).
+ */
+export interface AgentInventoryEntry {
+    agentId: string;
+    persona: string;
+    label: string;
+    description?: string;
+    modelClass: string;
+    packName: string;
+    packVersion: string;
+    toolAllowlist: string[];
+    hasHandoffSchemas: boolean;
+    memoryShape?: {
+        scratchpad?: boolean;
+        conversation?: boolean;
+        longTerm?: boolean;
+    };
+    confidenceThreshold?: number;
+    /** RFC 0072 §C — optional capability tiers this host does not satisfy, inert here. */
+    degraded?: string[];
+}
+/** Response body for `GET /v1/agents` (RFC 0072 §A). */
+export interface AgentInventoryResponse {
+    agents: AgentInventoryEntry[];
+    total: number;
+}
 //# sourceMappingURL=types.d.ts.map