@arnilo/prism 0.2.6 → 0.2.8

package/CHANGELOG.md

@@ -1,4 +1,12 @@
-# Changelog
+## [0.2.8] - 2026-08-18
+
+### Changed
+- **Release 0.2.8 (plan 028)** is the ACP adoption-fixes cut on the 0.2.x review-remediation line. API surface **additive-only** (plain reviewed compat gate at 0.2.8: expected deltas are the version literal plus the plan 028 additive exports — `ToolKind`/`ToolDefinition.kind`, `AgentFinishReason`/`agent_finished.finishReason`, `AgUiProjectedImage`/`AgUiProjectedToolResult`/`createCodingToolProjection`, `AcpCommand`/`AcpCommandsSeam`, `ERR_PRISM_ACP_RUN`, `acpImageBytes`/`acpCommandsPerUpdate`, and the new `@arnilo/prism-acp-agent` package; zero removals; baselines regenerated with `--update-baseline`, no `--allow-break`). Client names are scrubbed from the tree and `scripts/check-client-neutrality.mjs` is wired into `npm run release:gate`. ACP bugs B1–B5: truthful `usage_update` via a host `contextWindow` seam (omit when unknown); run-level `error` rejects `session/prompt` with `ERR_PRISM_ACP_RUN` (no fake transcript chunks); only boolean config options are advertised/`set_config_option` (select fails `ERR_PRISM_ACP_CAPABILITY`); `tool_call.kind` prefers registry `ToolDefinition.kind`; permission docs match SDK wire kinds (`allow_always`/`reject_always`). Features F1–F10: thinking → `agent_thought_chunk`; bounded redacted transcript replay on `session/load`/`resume`; spawnable `@arnilo/prism-acp-agent` over stdio; `session/prompt` `StopReason` fidelity; UNSTABLE-gated `plan_update`/`plan_removed` from coding plan lifecycle; host-owned `session_info_update` titles; opt-in `createCodingToolProjection()` for first-party edit/write diffs+locations; projected `toolResult` images as ACP content/image blocks (`acpImageBytes`); host slash commands as `available_commands_update` (`acpCommandsPerUpdate`); Windows sandbox policy documented (native backend stays Linux-only, fail-closed). Release graph is **51** publishable manifests at exact **0.2.8** (root + 50 workspace; `+1` `@arnilo/prism-acp-agent`). Store compatibility with 0.2.7: **compatible, no migration**. Exit gate green (`sdk:ready`, `release:check` including the client-neutrality guard, audit 0 moderate, scan-secrets 0, SBOM regenerated). **Publication remains the operator handoff** (`docs/release-and-install.md` `0.2.8 publish handoff` — signed `v0.2.8` tag + npm OIDC).
+
+## [0.2.7] - 2026-08-17
+
+### Changed
+- **Release 0.2.7 (plan 027)** is the enterprise ERP production-readiness cut on the 0.2.x review-remediation line. API surface **additive-only** (plain reviewed compat gate at 0.2.7: expected deltas are the version literal plus the plan 027 additive exports — ERP outbox/inbox stores + bounded dispatcher, saga compensation/reconciliation engine, multi-party SoD approvals, signed hash-chained audit export with WORM/SIEM seams, field-level classification + fail-closed redaction, deterministic ERP invariant evals; zero removals; baselines regenerated with `--update-baseline`, no `--allow-break`; freeze manifest `scripts/phase27-freeze-manifest.json` records per-task evidence tokens, state machines, caps, the demand registry, measured HA/DR/classification/journey numbers, and the 0.3.0 blocker). Nine roadmap items with threat model ERP-T1–ERP-T10, ownership/tenant tests, no exactly-once claim, no implicit credential discovery, package budget, docs entries, and protected end-to-end evidence: (1) **transactional outbox/inbox** (`erp-messaging`, Task 1) — `ErpOutboxStore`/`ErpInboxStore` + bounded `ErpOutboxDispatcher` with claim-token CAS, `FOR UPDATE SKIP LOCKED`, `ON CONFLICT DO NOTHING` idempotent append, at-least-once delivery with explicit unknown-outcome, dead-letter/replay requiring verified tenant `AgentIdentity`; migrations 004 (`prism_erp_outbox`/`prism_erp_inbox`). (2) **saga compensation and reconciliation** (`saga`, Task 2) — `defineSaga`/`runSaga`/`resumeSaga` over existing CheckpointStore + LeaseStore with reverse-order compensation, unknown-outcome detection, manual resolution requiring verified identity + bounded reason + audit ref, stable tenant-scoped operation keys, redacted snapshots, `MAX_SAGA_STEPS=100`. (3) **multi-party SoD approvals** (`approvals`, Task 3) — `ApprovalStore` with role/quorum rules, requester/approver separation, any-party-veto rejection, delegated authority (max depth 8), expiry checked at every protected transition, atomic grant consumption in the host transaction, `policyRevision` pin denying on mismatch; migration 005 (`prism_erp_approvals`). (4) **tamper-evident audit export** (`audit-export`, Task 4) — `createAuditExporter` with WORM-then-SIEM ordering, hash-chained record envelopes (genesis 0x64 zeros), `verifyAuditBatch` independent verification, `AuditCursorStore` CAS, SIEM best-effort pending replay (8-entry cap), legal-hold flag preservation, RFC 8785 canonical JSON for digests. (5) **secret-manager adapters** (Task 5) — Vault/AWS/Azure/GCP stay **deferred** behind the demand gate (no named consumer; no adapter ships; `scripts/phase27-demand-gate.mjs` enforces zero ambient discovery). (6) **HA registries and recovery** (`ha-dr`, Task 6) — two-replica drill on real Postgres proves failover within lease TTL+5s (measured 4100 ms vs 9000 ms ceiling), idempotent outbox re-append on uncertain-commit replay, stale fence/revision write rejection, exactly-one lease owner, tenant isolation fail-closed. (7) **backup/restore/migration rollback evidence** (Task 7) — `pg_dump`/`pg_restore` custom-format backup (108,291 B / 122 ms / 382 ms restore), 0.2.6→0.2.7 migration forward+rollback rehearsed (5 migrations), PITR RPO 0 s / RTO 1 s (recovery 1163 ms); production rollback is roll-forward repair only (no down migrations). (8) **field-level classification and fail-closed redaction** (`field-policy`, Task 8) — `applyFieldPolicy`/`FieldPolicy`/`createProtectedFieldPolicy` at the redaction, audit-export, and OpenTelemetry seams; unknown-label deny-on-outbound fail-closed default, sparse-copy walker, measured overhead peak 99.8% of the redactor-walk baseline (cap 110%). (9) **ERP release journey** (`erp-evals`, Task 9) — `erpInvariantDataset` + `createErpInvariantScorers` (8 hard 0/1 gates consuming structured facts only) + `scripts/phase27-erp-journey.test.mjs` exercising identity/policy/budget/SoD-approval/outbox/saga-compensation/audit-export/legal-hold/classification/failover/restore end-to-end (4815 ms, all 8 invariants pass). Release graph stays **50** publishable manifests at exact **0.2.7**; zero new runtime dependency names (core remains dependency-free). Store compatibility with 0.2.6: **compatible, additive** (two new ERP migrations 004/005 + outbox/inbox/approvals tables; rollback = stop 0.2.7 workers, restore the 0.2.6 manifests/tag — see `docs/migration.md` `0.2.6 → 0.2.7`). Exit gate green (core + script gates incl. `phase27-freeze` 9, `phase27-release` 12, `phase27-ha`/`phase27-dr`/`phase27-erp-journey` protected legs, coverage gate, `sdk:ready`, audit 0 moderate, pack dry-run 50/50 twice byte-identical, plain reviewed compat gate at 0.2.7 — version literal + additive exports only, release-evidence manifest with zero blocked surfaces, evidence in `scripts/phase27-release-evidence.json`). **"ERP production ready" remains blocked until the 0.3.0 live-service matrix is recorded** — passing 0.2.7 gates unblocks the release cut, not the 0.3.0 live-service matrix. **Publication remains the operator handoff** (`docs/release-and-install.md` `0.2.7 publish handoff` — signed `v0.2.7` tag + npm OIDC).
 
 ## [0.2.6] - 2026-08-16
 
@@ -109,7 +117,7 @@
 ### Changed
 - `@arnilo/prism-ag-ui` depends on `@arnilo/prism-coding-agent` (workspace) for Phase 9 output-chunk caps and lifecycle types; publishable graph stays **48** manifests.
 - SBOM license policy allows `Unlicense` (tweetnacl via `@nats-io/nkeys`); readiness SBOM evidence refreshed (227 packages / 12 licenses).
-- `@arnilo/prism-ag-ui/renderer` now exports the DOM-free A2UI core values (`A2UiSurfaceState`, `reduceA2UiOps`, `readA2UiBatch`, `resolvePointer`, `A2UI_VERSION`) — Synapta FR, hosts can drive the surface state machine without mounting; `createA2UiRenderer` behavior and frozen A2UI caps unchanged.
+- `@arnilo/prism-ag-ui/renderer` now exports the DOM-free A2UI core values (`A2UiSurfaceState`, `reduceA2UiOps`, `readA2UiBatch`, `resolvePointer`, `A2UI_VERSION`) — host FR, hosts can drive the surface state machine without mounting; `createA2UiRenderer` behavior and frozen A2UI caps unchanged.
 
 ### Breaking (advertise/surface for ACP hosts only)
 - `initialize` advertisement now reflects wired seams (previously minimal close-session); new session methods are registered only with their seams; `session/resume` of a live session rejects; `agentInfo.version` now comes from the package.json. Core, AG-UI, and coding-agent behavior unchanged. See [migration guide](docs/migration.md) `0.0.26 → 0.0.27`.

package/README.md

@@ -11,6 +11,7 @@ packages. Prism defines contracts, not apps.
 - **Agent/session runtime**: `createAgent`/`createAgentSession`, run prompts,
   dispatch host tools, subscribe to normalized `AgentEvent` streams, abort runs,
   compact, and navigate branches.
+- **Field-level classification (0.2.7)**: `applyFieldPolicy` + the fail-closed protected default walk JSON-like values across prompt/tool/artifact/audit/telemetry/persistence/export boundaries with `allow`/`redact`/`tokenize`/`deny` decisions, explicit per-boundary `labelFor` hints, bounded traversal, and sparse-copy allocation; seams at the egress redaction functions, the audit-export redactor hook, and the OpenTelemetry attribute policy. See [docs/data-classification.md](docs/data-classification.md).
 - **Providers and models**: provider/model registries, provider event helpers,
   credential redaction helpers, mock provider, and an optional
   OpenAI-compatible provider subpath. Cache support is provider-specific:
@@ -55,7 +56,7 @@ npm install @arnilo/prism @arnilo/prism-provider-openai    # core + one provider
 npm install @arnilo/prism-base                              # core + compaction + validation
 npm install @arnilo/prism-code @arnilo/prism-provider-openai # coding-agent profile
 npm install @arnilo/prism-sdk @arnilo/prism-provider-openai  # application profile
-npm install @arnilo/prism-all                               # broad umbrella (20 direct / 43 transitive packages)
+npm install @arnilo/prism-all                               # broad umbrella (21 direct / 44 transitive packages)
 npm install @arnilo/prism-server @arnilo/prism-workflows    # optional Web API boundary
 npm install @arnilo/prism-supervisor                         # optional local delegation + A2A 1.0
 npm install @arnilo/prism-web-tools                          # optional bounded Brave/Exa/Firecrawl research
@@ -182,7 +183,7 @@ printf '{"id":"1","command":"prompt","params":{"input":"Hi"}}\n' \
 | `@arnilo/prism-base` | profile: core + compaction + JSON Schema validation |
 | `@arnilo/prism-code` | profile: base + coding tools/security + MCP |
 | `@arnilo/prism-sdk` | profile: base + workflows + MCP + credentials + OpenTelemetry |
-| `@arnilo/prism-all` | broad umbrella: 20 first-party packages (43 transitive) across runtime, capability, provider, and persistence — omits document-reader, OpenAPI tools, NATS, Caveman, and Ponytail |
+| `@arnilo/prism-all` | broad umbrella: 21 first-party packages (44 transitive) across runtime, capability, provider, and persistence — omits document-reader, OpenAPI tools, NATS, Caveman, and Ponytail |
 
 ## Scripts
 

package/dist/agent-loops.js

@@ -47,6 +47,9 @@ export const singleShotLoop = {
             ctx.emit({ type: "turn_finished", sessionId: ctx.sessionId, runId: ctx.runId, turn });
             const dispatchable = dispatchableToolCalls(calls);
             if (dispatchable.length === 0 || toolRounds >= ctx.maxToolRounds) {
+                // F4: the tool-round ceiling ended the run cleanly (not a natural end).
+                if (dispatchable.length > 0 && toolRounds >= ctx.maxToolRounds)
+                    ctx.finishReason = "turn_limit";
                 // Soft-interrupt / late steer: keep same run going when queue still has text.
                 if (await ctx.applyPendingSteers?.()) {
                     nextInput = [];
@@ -155,6 +158,7 @@ export function generateValidateReviseLoop(opts) {
                             errors: [{ message: "maximum tool rounds exceeded" }],
                             metadata: { reason: "tool_round_limit" },
                         };
+                        ctx.finishReason = "turn_limit";
                         ctx.emit({ type: "artifact_failed", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt: attempts + 1, result });
                         return usage;
                     }

package/dist/agent-run-lifecycle.js

@@ -1,7 +1,7 @@
-import { agentFingerprint, loadAgentRunState, publicState, saveAgentRunState } from "./agent-run-state.js";
-import { AgentRunStateError } from "./contracts.js";
 import { assertValidAgentRunResume, pendingDecisionsOf, resolveRunDecisions } from "./agent-approval.js";
+import { agentFingerprint, loadAgentRunState, publicState, saveAgentRunState } from "./agent-run-state.js";
 import { RuntimeAgentSession, throwIfAbortedSignal } from "./agent-session.js";
+import { AgentRunStateError } from "./contracts.js";
 function assertAgentId(actual, expected) {
     if (expected !== undefined && actual !== expected)
         throw new AgentRunStateError("Agent run capability mismatch");

package/dist/agent-session/helpers.d.ts

@@ -1,7 +1,7 @@
 /** helpers (0.2.5 plan 025 Task 1 split). Moved verbatim from agent-session.ts; public surface unchanged behind the barrel. */
 import type { CompactionOptions, ContentBlock, ErrorInfo, Guardrails, Message, ProviderEvent, RetryOptions, ToolCallContent, Usage } from "../contracts.js";
-import type { AgentInput } from "../input.js";
 import { createId } from "../ids.js";
+import type { AgentInput } from "../input.js";
 export declare function providerContent(event: Extract<ProviderEvent, {
     type: "content_delta" | "tool_call";
 }>): ContentBlock;

package/dist/agent-session/helpers.js

@@ -1,6 +1,7 @@
+/** helpers (0.2.5 plan 025 Task 1 split). Moved verbatim from agent-session.ts; public surface unchanged behind the barrel. */
+import { singleShotLoop } from "../agent-loops.js";
 import { createId } from "../ids.js";
 import { reconstructToolCallDeltas } from "../provider-events.js";
-import { singleShotLoop } from "../agent-loops.js";
 export function providerContent(event) {
     return event.type === "content_delta" ? event.content : event.call;
 }

package/dist/agent-session/session.d.ts

@@ -1,8 +1,8 @@
 /** session (0.2.5 plan 025 Task 1 split). Moved verbatim from agent-session.ts; public surface unchanged behind the barrel. */
+import type { StoredAgentRunState } from "../agent-run-state.js";
 import type { Agent, AgentEvent, AgentRunResult, AgentRunStateOptions, AgentSession, AgentSessionConfig, CompactionOptions, CompactionResult, OwnershipScope, RunDecision, RunOptions, SessionEntry, SteerOptions, SubscribeOptions } from "../contracts.js";
 import type { AgentInput } from "../input.js";
 import type { LoadedSkillBodiesEntry } from "../skill-load.js";
-import type { StoredAgentRunState } from "../agent-run-state.js";
 export declare class RuntimeAgentSession implements AgentSession {
     readonly id: string;
     private readonly agent;

package/dist/agent-session/session.js

@@ -1,31 +1,32 @@
-import { AgentDecisionError, AgentDelegationSuspendedError, AgentLoopStateError, AgentRunError, AgentRunStateError, DEFAULT_MAX_PENDING_DECISIONS, DEFAULT_MAX_PENDING_STEERS, DEFAULT_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_DECISIONS, MAX_ATTRIBUTION_DEPTH, } from "../contracts.js";
+/** session (0.2.5 plan 025 Task 1 split). Moved verbatim from agent-session.ts; public surface unchanged behind the barrel. */
 import { AgentRunSuspended, decisionIdentityRef, decisionScopesEqual, nestedApprovalId, nestedOutcomeToolResult, pathsEqual, } from "../agent-approval.js";
-import { identityTelemetryAttributes, ownershipFromIdentity, resolveRunIdentity } from "../identity.js";
-import { assembleProviderInput } from "../input.js";
-import { GuardrailError, assertGuardrailsAllowed, runGuardrails } from "../guardrails.js";
-import { applyRestoredSkillBodies, snapshotLoadedSkillBodies, validateLoadedSkillBodies } from "../skill-load.js";
+import { resolveLoop, resolveToolConcurrency } from "../agent-loops.js";
 import { boundedLoopSnapshot, initialAgentRunState, publicState, saveAgentRunState, validateRunStateOptions } from "../agent-run-state.js";
-import { RunLimitError, RunLimitTracker, resolveRunLimits } from "../run-limits.js";
-import { errorToErrorInfo, redactAgentEvent, redactProviderRequest, redactRunLedgerRecord, redactSecrets, redactSessionEntry, } from "../redaction.js";
-import { createMemorySessionStore, createSessionEntry, getSessionBranchEntries, rebuildSessionContext } from "../session-stores.js";
 import { activeTools, policyList, toolElicitationRequest } from "../agent-tool-dispatch.js";
-import { assertStructuredOutputRequestSupported, resolveRunProviderOptions } from "../structured-output.js";
-import { canonicalToolEffectJson, toolEffectArgumentsHash } from "../tool-effects.js";
-import { composeSystemPrompt, mergeSystemPromptConfig } from "../system-prompts.js";
 import { createDefaultCompactionStrategy, isCompactionEntryData } from "../compaction.js";
-import { createDefaultRetryPolicy, waitForRetry } from "../retry.js";
-import { createLoadedSkillSet, resolveSkillsDisclosure } from "../skill-disclosure.js";
-import { createProviderRequestPolicyChain, normalizeProviderRequestPolicyResult } from "../provider-request-policy.js";
+import { AgentDecisionError, AgentDelegationSuspendedError, AgentLoopStateError, AgentRunError, AgentRunStateError, DEFAULT_MAX_PENDING_DECISIONS, DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, HARD_MAX_PENDING_DECISIONS, MAX_ATTRIBUTION_DEPTH, } from "../contracts.js";
+import { assertGuardrailsAllowed, GuardrailError, runGuardrails } from "../guardrails.js";
+import { identityTelemetryAttributes, ownershipFromIdentity, resolveRunIdentity } from "../identity.js";
+import { assembleProviderInput } from "../input.js";
 import { createProviderTurnMetadata, readProviderHttpStatus } from "../observability.js";
-import { dispatchToolCall, resolveToolEffectDeclaration } from "../tools.js";
-import { isFlushableRunLedger } from "../run-ledger.js";
 import { providerToolCallDeltaContent } from "../provider-events.js";
+import { createProviderRequestPolicyChain, normalizeProviderRequestPolicyResult } from "../provider-request-policy.js";
+import { errorToErrorInfo, redactAgentEvent, redactProviderRequest, redactRunLedgerRecord, redactSecrets, redactSessionEntry, } from "../redaction.js";
+import { createDefaultRetryPolicy, waitForRetry } from "../retry.js";
+import { isFlushableRunLedger } from "../run-ledger.js";
+import { RunLimitError, RunLimitTracker, resolveRunLimits } from "../run-limits.js";
+import { createMemorySessionStore, createSessionEntry, getSessionBranchEntries, rebuildSessionContext } from "../session-stores.js";
+import { createLoadedSkillSet, resolveSkillsDisclosure } from "../skill-disclosure.js";
+import { applyRestoredSkillBodies, snapshotLoadedSkillBodies, validateLoadedSkillBodies } from "../skill-load.js";
 import { resolveActiveSkills } from "../skills.js";
-import { resolveLoop, resolveToolConcurrency } from "../agent-loops.js";
+import { assertStructuredOutputRequestSupported, resolveRunProviderOptions } from "../structured-output.js";
+import { composeSystemPrompt, mergeSystemPromptConfig } from "../system-prompts.js";
+import { canonicalToolEffectJson, toolEffectArgumentsHash } from "../tool-effects.js";
 import { resolveToolResultFold } from "../tool-result-fold.js";
-import { EventSubscriber } from "./event-subscriber.js";
-import { ProviderTurnFailure, SteerSoftInterrupt, bridgeAbort, createUsageAccumulator, errorFromInfo, finalAssistantMessage, inputToMessages, isDurableLoop, isSteerSoftInterrupt, jsonBytes, mergeCompaction, mergeGuardrails, mergeRetry, messageTextBytes, providerContent, randomId, reconstructMissingToolCalls, throwIfAborted, throwIfAbortedSignal, withoutTrailingInput, } from "./helpers.js";
+import { dispatchToolCall, resolveToolEffectDeclaration } from "../tools.js";
 import { createAgentSession } from "./create-agent.js";
+import { EventSubscriber } from "./event-subscriber.js";
+import { bridgeAbort, createUsageAccumulator, errorFromInfo, finalAssistantMessage, inputToMessages, isDurableLoop, isSteerSoftInterrupt, jsonBytes, mergeCompaction, mergeGuardrails, mergeRetry, messageTextBytes, ProviderTurnFailure, providerContent, randomId, reconstructMissingToolCalls, SteerSoftInterrupt, throwIfAborted, throwIfAbortedSignal, withoutTrailingInput, } from "./helpers.js";
 export class RuntimeAgentSession {
     id;
     agent;
@@ -850,7 +851,14 @@ export class RuntimeAgentSession {
                     loopState: undefined,
                 })
                 : undefined;
-            this.emit({ type: "agent_finished", sessionId: this.id, runId, usage });
+            this.emit({
+                type: "agent_finished",
+                sessionId: this.id,
+                runId,
+                usage,
+                // F4: loop strategies record why a ceiling ended the run cleanly (e.g. turn_limit).
+                ...(ctx.finishReason ? { finishReason: ctx.finishReason } : {}),
+            });
             return this.buildRunResult({ runId, status: "succeeded", usage, runState });
         }
         catch (error) {

package/dist/agent-session.d.ts

@@ -1,6 +1,6 @@
 /** agent-session.ts barrel (0.2.5 plan 025 Task 1 god-module split): re-exports the
  * public surface from cohesive family modules (0.1.4 barrel precedent). */
 export * from "./agent-session/create-agent.js";
-export * from "./agent-session/session.js";
 export * from "./agent-session/event-subscriber.js";
 export * from "./agent-session/helpers.js";
+export * from "./agent-session/session.js";

package/dist/agent-session.js

@@ -1,7 +1,7 @@
 /** agent-session.ts barrel (0.2.5 plan 025 Task 1 god-module split): re-exports the
  * public surface from cohesive family modules (0.1.4 barrel precedent). */
 export * from "./agent-session/create-agent.js";
-export * from "./agent-session/session.js";
 export * from "./agent-session/event-subscriber.js";
 export * from "./agent-session/helpers.js";
+export * from "./agent-session/session.js";
 //# sourceMappingURL=agent-session.js.map

package/dist/agents.d.ts

@@ -12,5 +12,5 @@
  * agents.d.ts and change the declared surface — the 0.1.4 promise is an
  * identical surface.
  */
-export { createAgent, createAgentSession } from "./agent-session.js";
 export { resumeAgentRun, resumeAgentRunStream } from "./agent-run-lifecycle.js";
+export { createAgent, createAgentSession } from "./agent-session.js";

package/dist/agents.js

@@ -12,6 +12,6 @@
  * agents.d.ts and change the declared surface — the 0.1.4 promise is an
  * identical surface.
  */
-export { createAgent, createAgentSession } from "./agent-session.js";
 export { resumeAgentRun, resumeAgentRunStream } from "./agent-run-lifecycle.js";
+export { createAgent, createAgentSession } from "./agent-session.js";
 //# sourceMappingURL=agents.js.map

package/dist/contracts-core/agent.d.ts

@@ -1,20 +1,20 @@
 /** Contracts-core agent family (0.2.5 plan 025 Task 1 split).
  * Moved verbatim from contracts-core.ts; public surface unchanged behind the barrel. */
+import type { InputAssemblyLayout, RunLedger, ToolDefinition, ToolEffectStore, ToolRegistry } from "../contracts-protocol.js";
 import type { AgentRunStateOptions, AgentSession } from "../contracts-run-state.js";
 import type { ContributionRegistries } from "../contributions.js";
-import type { InputAssemblyLayout, RunLedger, ToolDefinition, ToolEffectStore, ToolRegistry } from "../contracts-protocol.js";
 import type { MiddlewareRegistry } from "../middleware.js";
-import type { PermissionPolicy, TrustPolicy } from "../security.js";
 import type { SecretRedactor } from "../redaction.js";
+import type { PermissionPolicy, TrustPolicy } from "../security.js";
 import type { ToolValidator } from "../tools.js";
-import type { AIProvider, ProviderRequestOptions, ProviderResolver } from "./provider.js";
-import type { AgentLoopOptions, AgentLoopStrategy } from "./loop.js";
 import type { CompactionOptions, RetryOptions } from "./compaction.js";
 import type { ContentBlock, ErrorInfo, JsonObject, Message, ModelConfig } from "./content.js";
 import type { ProviderRequestPolicy, SystemPromptConfig } from "./extensions.js";
-import type { Guardrails, RunLimits } from "./run-limits.js";
+import type { AgentLoopOptions, AgentLoopStrategy } from "./loop.js";
 import type { OwnershipScope } from "./persistence.js";
+import type { AIProvider, ProviderRequestOptions, ProviderResolver } from "./provider.js";
 import type { ResourceLoader } from "./resources.js";
+import type { Guardrails, RunLimits } from "./run-limits.js";
 import type { SessionStore } from "./session.js";
 export interface AgentDefinition {
     readonly name: string;

package/dist/contracts-core/agent.js

@@ -1,3 +1,5 @@
+/** Contracts-core agent family (0.2.5 plan 025 Task 1 split).
+ * Moved verbatim from contracts-core.ts; public surface unchanged behind the barrel. */
 export {};
 /** Directory-name spelling for discovered contribution kinds. Maps to a
  *  {@link ManifestContributionDeclaration} kind for non-skill kinds:

package/dist/contracts-core/extensions.d.ts

@@ -1,15 +1,15 @@
 /** Contracts-core extensions family (0.2.5 plan 025 Task 1 split).
  * Moved verbatim from contracts-core.ts; public surface unchanged behind the barrel. */
+import type { ToolDefinition } from "../contracts-protocol.js";
 import type { ContributionRegistries } from "../contributions.js";
 import type { ManifestContributionDeclaration } from "../manifests.js";
 import type { Middleware, MiddlewareHookName, MiddlewareRegistry } from "../middleware.js";
-import type { ToolDefinition } from "../contracts-protocol.js";
-import type { AIProvider, ProviderRequest } from "./provider.js";
 import type { AgentDefinition, CommandDefinition, ContextProvider, InputBuilder, InstructionInjector, PromptBuilder, Skill } from "./agent.js";
 import type { CompactionStrategy, RetryPolicy } from "./compaction.js";
-import type { Credential, CredentialResolver, ResourceLoader, SettingsProvider } from "./resources.js";
 import type { ErrorInfo, ModelConfig } from "./content.js";
 import type { StoreFactory } from "./persistence.js";
+import type { AIProvider, ProviderRequest } from "./provider.js";
+import type { Credential, CredentialResolver, ResourceLoader, SettingsProvider } from "./resources.js";
 export type ContributionFileKind = "skill" | "tool" | "context" | "instructions";
 /** Inert envelope emitted by the host/CLI discovery scanner. Carries the
  *  realized {@link Skill} for skill kinds and a manifest-referenced

package/dist/contracts-core/extensions.js

@@ -1,2 +1,4 @@
+/** Contracts-core extensions family (0.2.5 plan 025 Task 1 split).
+ * Moved verbatim from contracts-core.ts; public surface unchanged behind the barrel. */
 export {};
 //# sourceMappingURL=extensions.js.map

package/dist/contracts-core/loop.d.ts

@@ -1,6 +1,6 @@
 /** Contracts-core loop family (0.2.5 plan 025 Task 1 split).
  * Moved verbatim from contracts-core.ts; public surface unchanged behind the barrel. */
-import type { AgentEvent, ProviderTurnResult, ToolResult } from "../contracts-protocol.js";
+import type { AgentEvent, AgentFinishReason, ProviderTurnResult, ToolResult } from "../contracts-protocol.js";
 import type { AgentInput } from "../input.js";
 import type { JsonValue, Message, ToolCallContent, Usage } from "./content.js";
 import type { ProviderRequest, StructuredOutputOptions } from "./provider.js";
@@ -13,6 +13,11 @@ export interface LoopContext {
     readonly input: AgentInput;
     readonly inputMessages: readonly Message[];
     readonly maxToolRounds: number;
+    /**
+     * Why the loop stopped, when a limit/ceiling ends the run cleanly (F4). Strategies set
+     * this at ceiling exits (e.g. `turn_limit`); the runtime copies it onto `agent_finished`.
+     */
+    finishReason?: AgentFinishReason;
     /** Maximum independent tool calls dispatched concurrently per provider turn. Default `1`. */
     readonly toolConcurrency: number;
     assemble(nextInput: AgentInput, toolResults?: readonly ToolResult[], turn?: number): Promise<ProviderRequest>;

package/dist/contracts-core/session.d.ts

@@ -1,8 +1,8 @@
 /** Contracts-core session family (0.2.5 plan 025 Task 1 split).
  * Moved verbatim from contracts-core.ts; public surface unchanged behind the barrel. */
 import type { AgentEvent } from "../contracts-protocol.js";
-import type { OwnershipScope, PersistencePage, PersistenceQuery } from "./persistence.js";
 import type { Message, ModelConfig } from "./content.js";
+import type { OwnershipScope, PersistencePage, PersistenceQuery } from "./persistence.js";
 export type SessionEntryKind = "message" | "event" | "summary" | "metadata" | "model_change" | "label" | "custom" | "compaction";
 export declare const SESSION_ENTRY_KINDS: readonly SessionEntryKind[];
 export declare const SESSION_ENTRY_SCHEMA_VERSION = 1;

package/dist/contracts-core.d.ts

@@ -2,13 +2,13 @@
  * public contracts surface from cohesive family modules so the import surface
  * of `./contracts-core.js` is unchanged (0.1.4 barrel precedent). */
 export type { AudioContent, DocumentContent, FileContent } from "./content.js";
-export * from "./contracts-core/content.js";
-export * from "./contracts-core/run-limits.js";
-export * from "./contracts-core/provider.js";
 export * from "./contracts-core/agent.js";
+export * from "./contracts-core/compaction.js";
+export * from "./contracts-core/content.js";
 export * from "./contracts-core/extensions.js";
-export * from "./contracts-core/session.js";
+export * from "./contracts-core/loop.js";
 export * from "./contracts-core/persistence.js";
-export * from "./contracts-core/compaction.js";
+export * from "./contracts-core/provider.js";
 export * from "./contracts-core/resources.js";
-export * from "./contracts-core/loop.js";
+export * from "./contracts-core/run-limits.js";
+export * from "./contracts-core/session.js";

package/dist/contracts-core.js

@@ -1,11 +1,11 @@
-export * from "./contracts-core/content.js";
-export * from "./contracts-core/run-limits.js";
-export * from "./contracts-core/provider.js";
 export * from "./contracts-core/agent.js";
+export * from "./contracts-core/compaction.js";
+export * from "./contracts-core/content.js";
 export * from "./contracts-core/extensions.js";
-export * from "./contracts-core/session.js";
+export * from "./contracts-core/loop.js";
 export * from "./contracts-core/persistence.js";
-export * from "./contracts-core/compaction.js";
+export * from "./contracts-core/provider.js";
 export * from "./contracts-core/resources.js";
-export * from "./contracts-core/loop.js";
+export * from "./contracts-core/run-limits.js";
+export * from "./contracts-core/session.js";
 //# sourceMappingURL=contracts-core.js.map

package/dist/contracts-protocol.d.ts

@@ -1,6 +1,5 @@
-import type { AgentLoopOptions, AgentLoopStrategy, ArtifactValidation, CompactionOptions, ContentBlock, ErrorInfo, GuardrailRecord, Guardrails, InstructionInjector, JsonObject, Message, ModelConfig, OwnershipScope, ProviderRequestPolicy, ProviderResolver, RetryOptions, RunLimitBreach, RunLimits, Skill, SubscriberOverflowPolicy, SystemPromptConfig, ToolCallAuthority, ToolCallContent, Usage } from "./contracts-core.js";
+import type { AgentLoopOptions, AgentLoopStrategy, ArtifactValidation, CompactionOptions, ContentBlock, ErrorInfo, GuardrailRecord, Guardrails, InstructionInjector, JsonObject, Message, ModelConfig, OwnershipScope, ProviderRequestOptions, ProviderRequestPolicy, ProviderResolver, RetryOptions, RunLimitBreach, RunLimits, Skill, SubscriberOverflowPolicy, SystemPromptConfig, ToolCallAuthority, ToolCallContent, Usage } from "./contracts-core.js";
 import type { AgentRunInterruption, AgentRunStateOptions } from "./contracts-run-state.js";
-import type { ProviderRequestOptions } from "./contracts-core.js";
 import type { SecretRedactor } from "./redaction.js";
 import type { ToolValidator } from "./tools.js";
 export type ProviderEvent = {
@@ -109,6 +108,7 @@ export interface ToolExecutionMetadata {
     readonly durationMs: number;
     readonly status: ToolCallStatus;
 }
+export type AgentFinishReason = "turn_limit" | "token_limit" | "refusal";
 export type AgentEvent = {
     readonly type: "agent_started";
     readonly sessionId: string;
@@ -118,6 +118,8 @@ export type AgentEvent = {
     readonly sessionId: string;
     readonly runId: string;
     readonly usage?: Usage;
+    /** Why the loop stopped, when a limit/ceiling ended the run cleanly (F4). Absent = natural end. */
+    readonly finishReason?: AgentFinishReason;
 } | {
     readonly type: "agent_suspended";
     readonly sessionId: string;
@@ -318,8 +320,12 @@ export interface ToolElicitationRequest {
     /** Answer-shape validation beyond structural schema checks; throw to reject the payload. */
     readonly validate?: (payload: JsonObject) => void;
 }
+/** Neutral tool-kind union mirroring the ACP `ToolKind` set (B4); never an ACP import in `src/`. */
+export type ToolKind = "read" | "edit" | "delete" | "move" | "search" | "execute" | "think" | "fetch" | "switch_mode" | "other";
 export interface ToolDefinition {
     readonly name: string;
+    /** Optional explicit kind; consumers (e.g. the ACP mapper) use it instead of name heuristics. */
+    readonly kind?: ToolKind;
     readonly description?: string;
     readonly parameters?: JsonObject;
     /** Force any provider turn containing this tool to dispatch sequentially. */

package/dist/contracts.d.ts

@@ -5,8 +5,8 @@
  * import surface of `./contracts.js` is unchanged.
  */
 export * from "./contracts-core.js";
-export * from "./contracts-run-state.js";
 export * from "./contracts-protocol.js";
+export * from "./contracts-run-state.js";
 /** Alias re-exports so `dist/contracts.d.ts` exposes implementer contract names. */
 export type AgentIdentity = import("./identity.js").AgentIdentity;
 export type Principal = import("./identity.js").Principal;

package/dist/contracts.js

@@ -5,6 +5,6 @@
  * import surface of `./contracts.js` is unchanged.
  */
 export * from "./contracts-core.js";
-export * from "./contracts-run-state.js";
 export * from "./contracts-protocol.js";
+export * from "./contracts-run-state.js";
 //# sourceMappingURL=contracts.js.map

package/dist/field-policy.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Field-level classification and fail-closed redaction (plan 027 Task 8).
+ *
+ * A dependency-free, JSON-like structured-value walker that evaluates an
+ * explicit host policy against every field of a value destined to cross a
+ * data boundary (provider prompt egress, tool dispatch/result persistence,
+ * artifact write/read/export, audit hashing, telemetry attributes/events,
+ * lifecycle export). The policy classifies fields by label, path, destination,
+ * and tenant; unknown fields fail closed under the protected default.
+ *
+ * Non-goals (frozen): no automatic sensitive-data discovery (labels come from
+ * an explicit `labelFor` hint function supplied by the boundary owner), no
+ * global registry, no decorator framework, no second policy language. Existing
+ * hardcoded secret redaction (`createSecretRedactor`) stays in place as
+ * defense in depth and runs *after* policy transformation at egress seams.
+ */
+export type FieldPolicyAction = "allow" | "redact" | "tokenize" | "deny";
+export interface FieldPolicyDecision {
+    readonly action: FieldPolicyAction;
+    /** Bounded reason recorded in audit redaction lists; never includes values. */
+    readonly reason?: string;
+}
+export interface FieldPolicyInput {
+    /** Dot/bracket path from the value root, e.g. `user.credentials[2].apiKey`. */
+    readonly path: string;
+    /** Boundary destination: prompt, tool, artifact, audit, telemetry, persistence, export, ... */
+    readonly destination: string;
+    /** Explicit caller-assigned label from `labelFor`; undefined = unknown. */
+    readonly label?: string;
+    readonly kind: "string" | "number" | "boolean" | "null" | "array" | "object";
+    readonly tenantId?: string;
+    readonly direction: "inbound" | "outbound";
+    readonly purpose?: string;
+}
+export type FieldPolicy = (input: FieldPolicyInput) => FieldPolicyDecision;
+export interface ApplyFieldPolicyOptions {
+    readonly destination: string;
+    readonly direction?: "inbound" | "outbound";
+    readonly tenantId?: string;
+    readonly purpose?: string;
+    /** Explicit key→label hints owned by the boundary; no automatic discovery. */
+    readonly labelFor?: (key: string, path: string) => string | undefined;
+    /** Called for every non-allow decision with {path, reason}; used by audit adapters. */
+    readonly onRedact?: (path: string, reason: string) => void;
+    readonly maxDepth?: number;
+    readonly maxKeys?: number;
+    readonly maxChars?: number;
+    /** Wall-clock budget for the whole walk; a slow policy trips it (fail closed). */
+    readonly maxPolicyMs?: number;
+    /** Deterministic token prefix (stable across runs; safe for audit chains). */
+    readonly tokenPrefix?: string;
+}
+export declare class FieldPolicyError extends Error {
+    readonly code = "ERR_PRISM_FIELD_POLICY";
+    readonly path: string;
+    constructor(path: string, message: string);
+}
+export declare const FIELD_POLICY_LIMITS: Readonly<{
+    readonly maxDepth: 32;
+    readonly maxKeys: 10000;
+    readonly maxChars: 1000000;
+    readonly maxPolicyMs: 5000;
+    readonly tokenPrefix: "tok_";
+}>;
+/**
+ * Applies `policy` to every field of a JSON-like value.
+ *
+ * Decisions: `allow` keeps the value; `redact` replaces string leaves with
+ * `[REDACTED]` while preserving container shape; `tokenize` replaces string
+ * leaves with a deterministic token; `deny` replaces the value with `[DENIED]`.
+ * Unknown labels fail closed under the protected default. Hostile values
+ * (cycles, unsupported types, over-budget walks) throw `FieldPolicyError`
+ * instead of stringifying guesses. The input is never mutated; only fields the
+ * policy changed are allocated.
+ */
+export declare function applyFieldPolicy<T>(value: T, policy: FieldPolicy, options: ApplyFieldPolicyOptions): T;
+export interface ProtectedFieldPolicyOptions {
+    /** Labels allowed to cross outbound/persisted boundaries unchanged. */
+    readonly publicLabels?: readonly string[];
+    /** Labels denied with the given reason; default `secret` and `financial`. */
+    readonly deniedLabels?: Readonly<Record<string, string>>;
+    /** Labels redacted with the given reason; default `personal`. */
+    readonly redactedLabels?: Readonly<Record<string, string>>;
+    /** Labels tokenized; default none. */
+    readonly tokenizedLabels?: Readonly<Record<string, string>>;
+}
+/**
+ * Fail-closed default for the protected profile (frozen behavior):
+ * unknown labels are denied on outbound boundaries and allowed inbound;
+ * `secret`/`financial` denied, `personal` redacted, listed public labels
+ * allowed. Labels are never auto-discovered — `labelFor` decides them.
+ */
+export declare function createProtectedFieldPolicy(options?: ProtectedFieldPolicyOptions): FieldPolicy;
+/** Identity policy: every field allowed (explicit override for trusted marks). */
+export declare const ALLOW_FIELD_POLICY: FieldPolicy;
+export interface AuditFieldRedaction {
+    readonly path: string;
+    readonly reason: string;
+}
+/** Structural match for `AuditRedactionPolicy` in @arnilo/prism-policy. */
+export interface AuditFieldRedactorLike {
+    apply(record: Readonly<Record<string, unknown>>): {
+        record: Readonly<Record<string, unknown>>;
+        redactions?: readonly AuditFieldRedaction[];
+    };
+}
+export interface AuditFieldRedactorOptions {
+    readonly tenantId?: string;
+    readonly purpose?: string;
+    readonly labelFor?: (key: string, path: string) => string | undefined;
+    /** Default true; denial instead would fail export (protected profile fails closed). */
+    readonly collectProvenance?: boolean;
+}
+/**
+ * Adapts a `FieldPolicy` to the audit-export redaction hook. Transformation
+ * runs BEFORE canonical hashing so the exported chain verifies exactly.
+ * Only `{path, reason}` provenance survives; values never echo into the list.
+ */
+export declare function createAuditFieldRedactor(policy: FieldPolicy, options?: AuditFieldRedactorOptions): AuditFieldRedactorLike;