@axiastudio/aioc 0.1.0-alpha.4 → 0.1.0-beta.1

package/README.md

@@ -1,6 +1,8 @@
 # @axiastudio/aioc
 
-AIOC is a lightweight internal agent SDK with an IoC-oriented control plane.
+AIOC is a governance-first SDK for LLM agents: models can propose actions, while deterministic policies and runtime controls enforce decisions.
+It provides default-deny gates for tools and handoffs, end-to-end auditability (run records, prompt snapshots, request fingerprints), and a foundation for verifiable iteration on prompts and policies.
+AIOC is designed for enterprise and public-sector contexts with privacy-by-design and AI Act-aligned governance requirements.
 
 Project home: [https://github.com/axiastudio/aioc](https://github.com/axiastudio/aioc)
 
@@ -8,6 +10,9 @@ Project home: [https://github.com/axiastudio/aioc](https://github.com/axiastudio
 
 This package is currently in alpha and is not production-ready.
 Breaking changes may occur before a stable release.
+Alpha contract reference: `docs/ALPHA-CONTRACT.md`.
+Pre-beta contract freeze reference: `docs/BETA-CONTRACT.md`.
+Privacy baseline reference: `docs/PRIVACY-BASELINE.md`.
 
 ## Contact
 
@@ -29,6 +34,13 @@ Governance implementation reference:
 - `docs/RFC-0001-governance-first-runtime.md`
 - `docs/RFC-0002-policy-gates-for-tools-and-handoffs.md`
 - `docs/RFC-0003-run-record-audit-trail-and-persistence.md`
+- `docs/ALPHA-CONTRACT.md`
+- `docs/BETA-CONTRACT.md`
+- `docs/PRIVACY-BASELINE.md`
+
+Canonical examples reference:
+
+- `docs/CANONICAL-EXAMPLES.md`
 
 ## Goals of this first scaffold
 
@@ -39,6 +51,7 @@ Governance implementation reference:
 ## Exposed primitives (v0 scaffold)
 
 - `Agent`, `RunContext`
+- optional `Agent.promptVersion` to version resolved instructions
 - `Tool`, `tool(...)`
 - agent handoffs via `Agent({ handoffs: [...] })`
 - `run(...)` with streaming support
@@ -49,6 +62,9 @@ Governance implementation reference:
 - provider setup helpers `setupMistral(...)`, `setupOpenAI(...)`, `setupProvider(...)`
 - stdout logger helper `createStdoutLogger(...)` (opt-in)
 - run record hook via `run(..., { record })` for external persistence/audit adapters
+- run record prompt snapshots per turn (`turn`, `agentName`, `promptVersion`, `promptHash`, optional `promptText`)
+- run record request fingerprints per turn (`requestHash`, segment hashes, `runtimeVersion`, `fingerprintSchemaVersion`)
+- JSON helper `toJsonValue(...)` to map runtime artifacts (for example `RunRecord.items`) into JSON-safe values for storage adapters
 - message helpers `user(...)`, `assistant(...)`, `system(...)`
 - `setDefaultProvider(...)`
 - error classes including `OutputGuardrailTripwireTriggered`
@@ -66,6 +82,16 @@ Policy deny notes:
 - Default deny behavior raises typed runtime errors (`ToolCallPolicyDeniedError` / `HandoffPolicyDeniedError`).
 - Policies can choose `denyMode: "tool_result"` to return a denied tool result to the model without throwing.
 
+Run record metadata convention:
+
+- `record.metadata.appBuildVersion` is a recommended field to correlate run drift with application-layer source/build changes.
+
+Privacy baseline highlights:
+
+- `record.includePromptText` defaults to `false` and should remain disabled unless explicitly required.
+- `record.contextRedactor` should be considered mandatory for production run-record persistence.
+- sink adapters should implement encryption, access controls, retention, and deletion policies.
+
 ## Test Commands
 
 - `npm run test:unit`
@@ -73,6 +99,39 @@ Policy deny notes:
 - `npm run test:regression`
 - `npm run test:ci`
 
+## Canonical Examples
+
+- `npm run example:hello` (minimal single-agent run)
+- `npm run example:tool-policy` (tool calls with deterministic policy gate)
+- `npm run example:run-record` (run record persistence with redaction + audit)
+- `npm run example:non-regression` (advanced v1/v2 run-record diff)
+
+## Python Alpha Port
+
+Python runtime is available under `py/` (Python 3.11+), with governance-first parity against core TS semantics:
+
+- `Agent`, `RunContext`, `run(...)` (stream/non-stream), tool registration, handoff
+- deterministic default-deny policy gates for tool/handoff
+- unified tool/handoff output envelope `{ status, code, publicReason, data }`
+- typed runtime errors for deny/guardrail/max-turns
+- run record sink adapter + context redaction + policy/guardrail decision capture
+- provider setup helpers: `setup_mistral()`, `setup_openai()`, `setup_provider()`
+- JSON-safe helper `to_json_value(...)`
+
+Python test command:
+
+- `cd py && python3 -m unittest discover -s tests -p 'test_*.py'`
+
+Python examples:
+
+- `cd py && python3 examples/basic/hello_world.py`
+- `cd py && python3 examples/basic/tool_policy_allow_deny.py`
+- `cd py && python3 examples/basic/run_record_sink.py`
+
+Migration mapping reference:
+
+- `docs/TS-PY-MIGRATION.md`
+
 ## License
 
 - Project license: `MIT` (`LICENSE`)

package/dist/agent.d.ts

@@ -7,6 +7,7 @@ export interface AgentConfiguration<TContext = unknown> {
     name: string;
     handoffDescription?: string;
     instructions?: AgentInstructions<TContext>;
+    promptVersion?: string;
     model?: string;
     modelSettings?: ModelSettings;
     tools?: Tool<TContext>[];
@@ -17,6 +18,7 @@ export declare class Agent<TContext = unknown> {
     name: string;
     handoffDescription: string;
     instructions?: AgentInstructions<TContext>;
+    promptVersion?: string;
     model?: string;
     modelSettings?: ModelSettings;
     tools: Tool<TContext>[];

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,MAAM,MAAM,iBAAiB,CAAC,QAAQ,GAAG,OAAO,IAC5C,MAAM,GACN,CAAC,CAAC,UAAU,EAAE,UAAU,CAAC,QAAQ,CAAC,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;AAErE,MAAM,WAAW,kBAAkB,CAAC,QAAQ,GAAG,OAAO;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,YAAY,CAAC,EAAE,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,KAAK,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;IAC7B,gBAAgB,CAAC,EAAE,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC;CAChD;AAED,qBAAa,KAAK,CAAC,QAAQ,GAAG,OAAO;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,CAAC,EAAE,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;IACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;IAC5B,gBAAgB,EAAE,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAElC,MAAM,EAAE,kBAAkB,CAAC,QAAQ,CAAC;IAWhD,MAAM,CAAC,MAAM,CAAC,QAAQ,GAAG,OAAO,EAC9B,MAAM,EAAE,kBAAkB,CAAC,QAAQ,CAAC,GACnC,KAAK,CAAC,QAAQ,CAAC;IAIZ,mBAAmB,CACvB,UAAU,EAAE,UAAU,CAAC,QAAQ,CAAC,GAC/B,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;CAS/B"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,MAAM,MAAM,iBAAiB,CAAC,QAAQ,GAAG,OAAO,IAC5C,MAAM,GACN,CAAC,CAAC,UAAU,EAAE,UAAU,CAAC,QAAQ,CAAC,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;AAErE,MAAM,WAAW,kBAAkB,CAAC,QAAQ,GAAG,OAAO;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,YAAY,CAAC,EAAE,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC3C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,KAAK,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;IAC7B,gBAAgB,CAAC,EAAE,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC;CAChD;AAED,qBAAa,KAAK,CAAC,QAAQ,GAAG,OAAO;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,CAAC,EAAE,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC3C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;IACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;IAC5B,gBAAgB,EAAE,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAElC,MAAM,EAAE,kBAAkB,CAAC,QAAQ,CAAC;IAYhD,MAAM,CAAC,MAAM,CAAC,QAAQ,GAAG,OAAO,EAC9B,MAAM,EAAE,kBAAkB,CAAC,QAAQ,CAAC,GACnC,KAAK,CAAC,QAAQ,CAAC;IAIZ,mBAAmB,CACvB,UAAU,EAAE,UAAU,CAAC,QAAQ,CAAC,GAC/B,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;CAS/B"}

package/dist/agent.js

@@ -5,6 +5,7 @@ class Agent {
     name;
     handoffDescription;
     instructions;
+    promptVersion;
     model;
     modelSettings;
     tools;
@@ -14,6 +15,7 @@ class Agent {
         this.name = config.name;
         this.handoffDescription = config.handoffDescription ?? "";
         this.instructions = config.instructions;
+        this.promptVersion = config.promptVersion;
         this.model = config.model;
         this.modelSettings = config.modelSettings;
         this.tools = config.tools ?? [];

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from "./agent";
 export * from "./config";
 export * from "./errors";
 export * from "./guardrails";
+export * from "./json";
 export * from "./logger";
 export * from "./messages";
 export * from "./policy";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,OAAO,CAAC;AACtB,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,OAAO,CAAC;AACtB,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -18,6 +18,7 @@ __exportStar(require("./agent"), exports);
 __exportStar(require("./config"), exports);
 __exportStar(require("./errors"), exports);
 __exportStar(require("./guardrails"), exports);
+__exportStar(require("./json"), exports);
 __exportStar(require("./logger"), exports);
 __exportStar(require("./messages"), exports);
 __exportStar(require("./policy"), exports);

package/dist/json.d.ts

@@ -0,0 +1,7 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+export declare function toJsonValue(value: unknown): JsonValue;
+//# sourceMappingURL=json.d.ts.map

package/dist/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAC7D,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,UAAU,GAAG,SAAS,EAAE,CAAC;AAEjE,MAAM,WAAW,UAAU;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B;AAmCD,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAMrD"}

package/dist/json.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toJsonValue = toJsonValue;
+function createJsonReplacer() {
+    const seen = new WeakSet();
+    return (_key, value) => {
+        if (typeof value === "bigint") {
+            return value.toString();
+        }
+        if (typeof value === "function" || typeof value === "symbol") {
+            return null;
+        }
+        if (value instanceof Map) {
+            return Object.fromEntries(value.entries());
+        }
+        if (value instanceof Set) {
+            return Array.from(value.values());
+        }
+        if (value instanceof Error) {
+            return {
+                name: value.name,
+                message: value.message,
+            };
+        }
+        if (value && typeof value === "object") {
+            if (seen.has(value)) {
+                return "[Circular]";
+            }
+            seen.add(value);
+        }
+        return value;
+    };
+}
+function toJsonValue(value) {
+    const serialized = JSON.stringify(value, createJsonReplacer());
+    if (typeof serialized === "undefined") {
+        return null;
+    }
+    return JSON.parse(serialized);
+}

package/dist/run-record.d.ts

@@ -24,6 +24,31 @@ export interface GuardrailDecisionRecord {
     reason?: string;
     metadata?: Record<string, unknown>;
 }
+export interface PromptSnapshotRecord {
+    timestamp: string;
+    turn: number;
+    agentName: string;
+    model?: string;
+    promptVersion?: string;
+    promptHash: string;
+    promptText?: string;
+}
+export interface RequestFingerprintRecord {
+    timestamp: string;
+    turn: number;
+    agentName: string;
+    providerName: string;
+    model: string;
+    runtimeVersion: string;
+    fingerprintSchemaVersion: string;
+    requestHash: string;
+    systemPromptHash: string;
+    messagesHash: string;
+    toolsHash: string;
+    modelSettingsHash: string;
+    messageCount: number;
+    toolCount: number;
+}
 export interface RunRecord<TContext = unknown> {
     runId: string;
     startedAt: string;
@@ -37,6 +62,8 @@ export interface RunRecord<TContext = unknown> {
     contextSnapshot: TContext;
     contextRedacted?: boolean;
     items: AgentInputItem[];
+    promptSnapshots: PromptSnapshotRecord[];
+    requestFingerprints: RequestFingerprintRecord[];
     policyDecisions: PolicyDecisionRecord[];
     guardrailDecisions?: GuardrailDecisionRecord[];
     errorName?: string;
@@ -56,6 +83,7 @@ export interface RunRecordOptions<TContext = unknown> {
     runId?: string;
     metadata?: Record<string, unknown>;
     contextRedactor?: RunRecordContextRedactor<TContext>;
+    includePromptText?: boolean;
     sink?: RunRecordSink<TContext> | RunRecordWriter<TContext>;
 }
 //# sourceMappingURL=run-record.d.ts.map

package/dist/run-record.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-record.d.ts","sourceRoot":"","sources":["../src/run-record.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"run-record.d.ts","sourceRoot":"","sources":["../src/run-record.ts"],"names":[],"mappings":"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"}

package/dist/run-recorder-runtime.d.ts

@@ -1,7 +1,20 @@
-import type { GuardrailDecisionRecord, PolicyDecisionRecord, RunRecordOptions } from "./run-record";
+import type { GuardrailDecisionRecord, PolicyDecisionRecord, PromptSnapshotRecord, RequestFingerprintRecord, RunRecordOptions } from "./run-record";
 import type { AgentInputItem } from "./types";
 export type PendingPolicyDecisionRecord = Omit<PolicyDecisionRecord, "timestamp">;
 export type PendingGuardrailDecisionRecord = Omit<GuardrailDecisionRecord, "timestamp">;
+export type PendingPromptSnapshotRecord = Omit<PromptSnapshotRecord, "timestamp" | "promptHash" | "promptText"> & {
+    promptText?: string;
+};
+export type PendingRequestFingerprintRecord = Omit<RequestFingerprintRecord, "timestamp" | "runtimeVersion" | "fingerprintSchemaVersion" | "requestHash" | "systemPromptHash" | "messagesHash" | "toolsHash" | "modelSettingsHash" | "messageCount" | "toolCount"> & {
+    systemPrompt?: string;
+    messages: AgentInputItem[];
+    tools: Array<{
+        name: string;
+        description: string;
+        parameters: unknown;
+    }>;
+    modelSettings?: Record<string, unknown>;
+};
 interface RunRecorderCreateOptions<TContext> {
     input: string | AgentInputItem[];
     context: TContext;
@@ -21,14 +34,19 @@ export declare class RunRecorder<TContext = unknown> {
     private readonly providerName;
     private readonly metadata?;
     private readonly contextSnapshot;
+    private readonly includePromptText;
     private readonly policyDecisions;
     private readonly guardrailDecisions;
+    private readonly promptSnapshots;
+    private readonly requestFingerprints;
     private observedFinalOutput;
     private runRecordWritten;
     private constructor();
     static create<TContext = unknown>(options: RunRecorderCreateOptions<TContext>): Promise<RunRecorder<TContext>>;
     onPolicyDecision: (decision: PendingPolicyDecisionRecord) => void;
     onGuardrailDecision: (decision: PendingGuardrailDecisionRecord) => void;
+    onPromptSnapshot: (snapshot: PendingPromptSnapshotRecord) => void;
+    onRequestFingerprint: (fingerprint: PendingRequestFingerprintRecord) => void;
     onMessageOutput: (content: string) => void;
     emitCompleted(options: RunRecorderFinalizeOptions): Promise<void>;
     emitFailed(options: RunRecorderFinalizeOptions, error: unknown): Promise<void>;

package/dist/run-recorder-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-recorder-runtime.d.ts","sourceRoot":"","sources":["../src/run-recorder-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EACvB,oBAAoB,EAGpB,gBAAgB,EAEjB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,MAAM,MAAM,2BAA2B,GAAG,IAAI,CAC5C,oBAAoB,EACpB,WAAW,CACZ,CAAC;AACF,MAAM,MAAM,8BAA8B,GAAG,IAAI,CAC/C,uBAAuB,EACvB,WAAW,CACZ,CAAC;AAEF,UAAU,wBAAwB,CAAC,QAAQ;IACzC,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE,CAAC;IACjC,OAAO,EAAE,QAAQ,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAC;CAC5C;AAED,UAAU,0BAA0B;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,cAAc,EAAE,CAAC;CACzB;AAqFD,qBAAa,WAAW,CAAC,QAAQ,GAAG,OAAO;IACzC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAmC;IACnE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAA0B;IACpD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA4C;IAE5E,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA8B;IAC9D,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAiC;IACpE,OAAO,CAAC,mBAAmB,CAAM;IACjC,OAAO,CAAC,gBAAgB,CAAS;IAEjC,OAAO;WAkBM,MAAM,CAAC,QAAQ,GAAG,OAAO,EACpC,OAAO,EAAE,wBAAwB,CAAC,QAAQ,CAAC,GAC1C,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IAqBjC,gBAAgB,GAAI,UAAU,2BAA2B,KAAG,IAAI,CAK9D;IAEF,mBAAmB,GAAI,UAAU,8BAA8B,KAAG,IAAI,CAKpE;IAEF,eAAe,GAAI,SAAS,MAAM,KAAG,IAAI,CAEvC;IAEI,aAAa,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjE,UAAU,CACd,OAAO,EAAE,0BAA0B,EACnC,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,IAAI,CAAC;YAIF,IAAI;CAwCnB"}
+{"version":3,"file":"run-recorder-runtime.d.ts","sourceRoot":"","sources":["../src/run-recorder-runtime.ts"],"names":[],"mappings":"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"}

package/dist/run-recorder-runtime.js

@@ -1,6 +1,96 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RunRecorder = void 0;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const REQUEST_FINGERPRINT_SCHEMA_VERSION = "request-fingerprint.v1";
+function resolveRuntimeVersion() {
+    const envVersion = process.env.AIOC_RUNTIME_VERSION?.trim() ??
+        process.env.npm_package_version?.trim();
+    if (envVersion) {
+        return envVersion;
+    }
+    try {
+        const packageJsonPath = (0, node_path_1.resolve)(__dirname, "..", "package.json");
+        const packageJsonRaw = (0, node_fs_1.readFileSync)(packageJsonPath, "utf8");
+        const packageJson = JSON.parse(packageJsonRaw);
+        if (typeof packageJson.version === "string" &&
+            packageJson.version.trim().length > 0) {
+            return packageJson.version.trim();
+        }
+    }
+    catch {
+        // Fallback handled below.
+    }
+    return "unknown";
+}
+const RUNTIME_VERSION = resolveRuntimeVersion();
+function normalizeForHash(value, seen = new WeakSet()) {
+    if (value === null) {
+        return null;
+    }
+    const valueType = typeof value;
+    if (valueType === "string" ||
+        valueType === "number" ||
+        valueType === "boolean") {
+        return value;
+    }
+    if (valueType === "undefined") {
+        return "[undefined]";
+    }
+    if (valueType === "bigint") {
+        return `[bigint:${String(value)}]`;
+    }
+    if (valueType === "symbol") {
+        return `[symbol:${String(value)}]`;
+    }
+    if (valueType === "function") {
+        return "[function]";
+    }
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (value instanceof RegExp) {
+        return value.toString();
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => normalizeForHash(item, seen));
+    }
+    if (value instanceof Set) {
+        const entries = [...value].map((entry) => normalizeForHash(entry, seen));
+        entries.sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+        return entries;
+    }
+    if (value instanceof Map) {
+        const entries = [...value.entries()].map(([key, entry]) => [
+            normalizeForHash(key, seen),
+            normalizeForHash(entry, seen),
+        ]);
+        entries.sort((left, right) => JSON.stringify(left[0]).localeCompare(JSON.stringify(right[0])));
+        return entries;
+    }
+    if (value && typeof value === "object") {
+        const objectValue = value;
+        if (seen.has(objectValue)) {
+            return "[circular]";
+        }
+        seen.add(objectValue);
+        const normalized = {};
+        const keys = Object.keys(objectValue).sort();
+        for (const key of keys) {
+            normalized[key] = normalizeForHash(objectValue[key], seen);
+        }
+        seen.delete(objectValue);
+        return normalized;
+    }
+    return String(value);
+}
+function hashForFingerprint(value) {
+    return (0, node_crypto_1.createHash)("sha256")
+        .update(JSON.stringify(normalizeForHash(value)))
+        .digest("hex");
+}
 function extractQuestion(input) {
     if (typeof input === "string") {
         return input;
@@ -60,6 +150,9 @@ function toErrorSummary(error) {
         errorMessage: String(error),
     };
 }
+function hashPrompt(promptText) {
+    return (0, node_crypto_1.createHash)("sha256").update(promptText).digest("hex");
+}
 class RunRecorder {
     runRecordWriter;
     runRecordId;
@@ -68,11 +161,14 @@ class RunRecorder {
     providerName;
     metadata;
     contextSnapshot;
+    includePromptText;
     policyDecisions = [];
     guardrailDecisions = [];
+    promptSnapshots = [];
+    requestFingerprints = [];
     observedFinalOutput = "";
     runRecordWritten = false;
-    constructor(runRecordWriter, runRecordId, startedAt, question, providerName, metadata, contextSnapshot) {
+    constructor(runRecordWriter, runRecordId, startedAt, question, providerName, metadata, contextSnapshot, includePromptText) {
         this.runRecordWriter = runRecordWriter;
         this.runRecordId = runRecordId;
         this.startedAt = startedAt;
@@ -80,6 +176,7 @@ class RunRecorder {
         this.providerName = providerName;
         this.metadata = metadata;
         this.contextSnapshot = contextSnapshot;
+        this.includePromptText = includePromptText;
     }
     static async create(options) {
         const runRecordWriter = resolveRunRecordWriter(options.recordOptions);
@@ -87,7 +184,7 @@ class RunRecorder {
         const startedAt = new Date().toISOString();
         const question = extractQuestion(options.input);
         const contextSnapshot = await resolveContextSnapshot(options.context, options.recordOptions);
-        return new RunRecorder(runRecordWriter, runRecordId, startedAt, question, options.providerName, options.recordOptions?.metadata, contextSnapshot);
+        return new RunRecorder(runRecordWriter, runRecordId, startedAt, question, options.providerName, options.recordOptions?.metadata, contextSnapshot, options.recordOptions?.includePromptText ?? false);
     }
     onPolicyDecision = (decision) => {
         this.policyDecisions.push({
@@ -101,6 +198,50 @@ class RunRecorder {
             ...decision,
         });
     };
+    onPromptSnapshot = (snapshot) => {
+        const normalizedPrompt = snapshot.promptText ?? "";
+        this.promptSnapshots.push({
+            timestamp: new Date().toISOString(),
+            turn: snapshot.turn,
+            agentName: snapshot.agentName,
+            model: snapshot.model,
+            promptVersion: snapshot.promptVersion,
+            promptHash: hashPrompt(normalizedPrompt),
+            promptText: this.includePromptText ? normalizedPrompt : undefined,
+        });
+    };
+    onRequestFingerprint = (fingerprint) => {
+        const normalizedSystemPrompt = fingerprint.systemPrompt ?? "";
+        const normalizedModelSettings = fingerprint.modelSettings ?? {};
+        const normalizedTools = fingerprint.tools.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.parameters,
+        }));
+        const requestPayload = {
+            model: fingerprint.model,
+            systemPrompt: normalizedSystemPrompt,
+            messages: fingerprint.messages,
+            tools: normalizedTools,
+            modelSettings: normalizedModelSettings,
+        };
+        this.requestFingerprints.push({
+            timestamp: new Date().toISOString(),
+            turn: fingerprint.turn,
+            agentName: fingerprint.agentName,
+            providerName: fingerprint.providerName,
+            model: fingerprint.model,
+            runtimeVersion: RUNTIME_VERSION,
+            fingerprintSchemaVersion: REQUEST_FINGERPRINT_SCHEMA_VERSION,
+            requestHash: hashForFingerprint(requestPayload),
+            systemPromptHash: hashForFingerprint(normalizedSystemPrompt),
+            messagesHash: hashForFingerprint(fingerprint.messages),
+            toolsHash: hashForFingerprint(normalizedTools),
+            modelSettingsHash: hashForFingerprint(normalizedModelSettings),
+            messageCount: fingerprint.messages.length,
+            toolCount: normalizedTools.length,
+        });
+    };
     onMessageOutput = (content) => {
         this.observedFinalOutput = content;
     };
@@ -129,6 +270,8 @@ class RunRecorder {
             contextSnapshot: this.contextSnapshot.contextSnapshot,
             contextRedacted: this.contextSnapshot.contextRedacted,
             items: [...options.items],
+            promptSnapshots: [...this.promptSnapshots],
+            requestFingerprints: [...this.requestFingerprints],
             policyDecisions: [...this.policyDecisions],
             guardrailDecisions: this.guardrailDecisions.length > 0
                 ? [...this.guardrailDecisions]

package/dist/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAqBhC,OAAO,EACL,cAAc,EAEd,mBAAmB,EAGnB,SAAS,EACT,cAAc,EACd,gBAAgB,EACjB,MAAM,SAAS,CAAC;AASjB,KAAK,eAAe,CAAC,QAAQ,IAAI;IAC/B,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,SAAS,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;CAC5B,CAAC;AAymBF,qBAAa,iBAAiB,CAAC,QAAQ,GAAG,OAAO;IAC/C,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAA0C;IACxD,OAAO,CAAC,KAAK,CAA4B;gBAGvC,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,EAC/C,KAAK,EAAE,eAAe,CAAC,QAAQ,CAAC;IAMlC,QAAQ,IAAI,aAAa,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;IAQnD,IAAI,OAAO,IAAI,cAAc,EAAE,CAE9B;IAED,IAAI,SAAS,IAAI,KAAK,CAAC,QAAQ,CAAC,CAE/B;CACF;AAED,wBAAsB,GAAG,CAAC,QAAQ,GAAG,OAAO,EAC1C,aAAa,EAAE,KAAK,CAAC,QAAQ,CAAC,EAC9B,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE,EAChC,OAAO,EAAE,gBAAgB,CAAC,QAAQ,CAAC,GAClC,OAAO,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC,CAAC;AAExC,wBAAsB,GAAG,CAAC,QAAQ,GAAG,OAAO,EAC1C,aAAa,EAAE,KAAK,CAAC,QAAQ,CAAC,EAC9B,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE,EAChC,OAAO,CAAC,EAAE,mBAAmB,CAAC,QAAQ,CAAC,GACtC,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAuBhC,OAAO,EACL,cAAc,EAEd,mBAAmB,EAGnB,SAAS,EACT,cAAc,EACd,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAUjB,KAAK,eAAe,CAAC,QAAQ,IAAI;IAC/B,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,SAAS,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;CAC5B,CAAC;AAwpBF,qBAAa,iBAAiB,CAAC,QAAQ,GAAG,OAAO;IAC/C,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAA0C;IACxD,OAAO,CAAC,KAAK,CAA4B;gBAGvC,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,EAC/C,KAAK,EAAE,eAAe,CAAC,QAAQ,CAAC;IAMlC,QAAQ,IAAI,aAAa,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;IAQnD,IAAI,OAAO,IAAI,cAAc,EAAE,CAE9B;IAED,IAAI,SAAS,IAAI,KAAK,CAAC,QAAQ,CAAC,CAE/B;CACF;AAED,wBAAsB,GAAG,CAAC,QAAQ,GAAG,OAAO,EAC1C,aAAa,EAAE,KAAK,CAAC,QAAQ,CAAC,EAC9B,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE,EAChC,OAAO,EAAE,gBAAgB,CAAC,QAAQ,CAAC,GAClC,OAAO,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC,CAAC;AAExC,wBAAsB,GAAG,CAAC,QAAQ,GAAG,OAAO,EAC1C,aAAa,EAAE,KAAK,CAAC,QAAQ,CAAC,EAC9B,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE,EAChC,OAAO,CAAC,EAAE,mBAAmB,CAAC,QAAQ,CAAC,GACtC,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC"}

package/dist/run.js

@@ -9,6 +9,21 @@ const run_log_emitter_1 = require("./run-log-emitter");
 const run_recorder_runtime_1 = require("./run-recorder-runtime");
 const run_context_1 = require("./run-context");
 const zod_1 = require("zod");
+const zod_to_json_schema_1 = require("zod-to-json-schema");
+function toToolParameterSchema(schema) {
+    try {
+        const convert = zod_to_json_schema_1.zodToJsonSchema;
+        const rawSchema = convert(schema, { $refStrategy: "none" });
+        const normalized = { ...rawSchema };
+        delete normalized.$schema;
+        return normalized;
+    }
+    catch {
+        return {
+            type: "unserializable_tool_schema",
+        };
+    }
+}
 function normalizeInput(input) {
     if (typeof input === "string") {
         return [(0, messages_1.user)(input)];
@@ -238,7 +253,7 @@ async function evaluateOutputGuardrails(agent, runContext, history, outputText,
         await logEmitter.outputGuardrailPassed(agent.name, turn, guardrail.name);
     }
 }
-async function* runLoop(state, provider, runContext, maxTurns, logger, policies, onPolicyDecision, onGuardrailDecision) {
+async function* runLoop(state, provider, runContext, maxTurns, logger, policies, onPolicyDecision, onGuardrailDecision, onPromptSnapshot, onRequestFingerprint) {
     const logEmitter = new run_log_emitter_1.RunLogEmitter(logger);
     await logEmitter.runStarted(state.lastAgent.name, maxTurns, state.history.length);
     yield {
@@ -253,9 +268,32 @@ async function* runLoop(state, provider, runContext, maxTurns, logger, policies,
             const currentAgent = state.lastAgent;
             await logEmitter.turnStarted(currentAgent.name, activeTurn);
             const { providerTools, handoffRegistry } = buildTurnTools(currentAgent);
+            const model = resolveAgentModel(currentAgent);
+            const systemPrompt = await currentAgent.resolveInstructions(runContext);
+            onPromptSnapshot?.({
+                turn: activeTurn,
+                agentName: currentAgent.name,
+                model,
+                promptVersion: currentAgent.promptVersion,
+                promptText: systemPrompt,
+            });
+            onRequestFingerprint?.({
+                turn: activeTurn,
+                agentName: currentAgent.name,
+                providerName: provider.constructor.name,
+                model,
+                systemPrompt,
+                messages: state.history,
+                tools: providerTools.map((toolDefinition) => ({
+                    name: toolDefinition.name,
+                    description: toolDefinition.description,
+                    parameters: toToolParameterSchema(toolDefinition.parameters),
+                })),
+                modelSettings: currentAgent.modelSettings,
+            });
             const providerStream = provider.stream({
-                model: resolveAgentModel(currentAgent),
-                systemPrompt: await currentAgent.resolveInstructions(runContext),
+                model,
+                systemPrompt,
                 messages: state.history,
                 tools: providerTools,
                 modelSettings: currentAgent.modelSettings,
@@ -457,7 +495,7 @@ async function run(startingAgent, input, options = {}) {
         providerName: provider.constructor.name,
         recordOptions: options.record,
     });
-    const rawStream = runLoop(state, provider, runContext, maxTurns, options.logger, options.policies, runRecorder.onPolicyDecision, runRecorder.onGuardrailDecision);
+    const rawStream = runLoop(state, provider, runContext, maxTurns, options.logger, options.policies, runRecorder.onPolicyDecision, runRecorder.onGuardrailDecision, runRecorder.onPromptSnapshot, runRecorder.onRequestFingerprint);
     const runRecordSnapshot = () => ({
         agentName: state.lastAgent.name,
         model: state.lastAgent.model,