@graphorin/core 0.5.0

package/dist/types/run.js

@@ -0,0 +1,31 @@
+//#region src/types/run.ts
+/**
+* Snapshot helper used by `@graphorin/observability` aggregators to
+* convert the on-disk `usageByModel` shape into the canonical
+* {@link ModelUsage} array. Pure utility — kept in core so consumers
+* do not have to take an observability dependency just to flatten a
+* run-state breakdown.
+*
+* @stable
+*/
+function flattenUsageByModel(byModel) {
+	if (byModel === void 0) return [];
+	const out = [];
+	for (const [modelId, entry] of Object.entries(byModel)) {
+		const m = {
+			modelId,
+			promptTokens: entry.promptTokens,
+			completionTokens: entry.completionTokens,
+			totalTokens: entry.totalTokens,
+			callCount: entry.attemptCount,
+			...entry.reasoningTokens !== void 0 ? { reasoningTokens: entry.reasoningTokens } : {},
+			...entry.cost !== void 0 ? { cost: entry.cost } : {}
+		};
+		out.push(m);
+	}
+	return out;
+}
+
+//#endregion
+export { flattenUsageByModel };
+//# sourceMappingURL=run.js.map

package/dist/types/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","names":["out: ModelUsage[]","m: ModelUsage"],"sources":["../../src/types/run.ts"],"sourcesContent":["import type { Tracer } from '../contracts/tracer.js';\nimport type { HandoffRecord } from './handoff.js';\nimport type { Message } from './message.js';\nimport type { CompletedToolCall, ToolApproval } from './tool.js';\nimport type { ModelUsage, Usage, UsageAccumulator } from './usage.js';\n\n/**\n * Status of an in-flight or completed agent run. Append-only persistence\n * stores expose this verbatim on the `runs` table.\n *\n * @stable\n */\nexport type RunStatus = 'running' | 'completed' | 'failed' | 'aborted' | 'awaiting_approval';\n\n/**\n * Single step inside an agent run. The agent runtime appends one\n * `RunStep` per provider call.\n *\n * @stable\n */\nexport interface RunStep {\n  readonly stepNumber: number;\n  readonly startedAt: string;\n  readonly endedAt?: string;\n  readonly usage?: Usage;\n  readonly toolCalls: readonly CompletedToolCall[];\n  /**\n   * Stable agent id active for this step (changes after a handoff).\n   */\n  readonly agentId: string;\n}\n\n/**\n * Per-model usage breakdown carried alongside the aggregate\n * {@link Usage} on {@link RunState}. Populated by the per-step retry\n * loop when `Agent.fallbackModels` fires; for runs that never fall\n * back, the map carries a single entry for the primary model with\n * `attemptCount: 1`.\n *\n * The aggregate `RunState.usage` is always the sum of every entry's\n * `Usage` portion (the field is asserted in tests).\n *\n * @stable\n */\nexport interface RunStateUsageByModel {\n  readonly [modelId: string]: Usage & { readonly attemptCount: number };\n}\n\n/**\n * The full, serializable state of a run. The agent runtime persists this\n * to the checkpoint store on every `awaiting_approval` boundary, so a\n * separate process can resume the run.\n *\n * The shape is intentionally JSON-stable: every nested type is plain\n * `JSON`-encodable (no `Map`, no `Set`, no `Date`).\n *\n * @stable\n */\nexport interface RunState {\n  readonly id: string;\n  readonly agentId: string;\n  readonly currentAgentId: string;\n  readonly sessionId: string;\n  readonly userId?: string;\n  status: RunStatus;\n  readonly steps: RunStep[];\n  readonly messages: Message[];\n  readonly pendingApprovals: ToolApproval[];\n  readonly handoffs: HandoffRecord[];\n  readonly usage: Usage;\n  /**\n   * Per-model usage breakdown. Populated by the per-step retry loop\n   * when `Agent.fallbackModels` fires (RB-48 / suggested DEC-164 /\n   * suggested ADR-052). Backward-compat: rehydrating a serialized\n   * state that omits the field synthesizes a single-entry map for\n   * the primary model.\n   */\n  usageByModel?: RunStateUsageByModel;\n  /**\n   * AG-19: coarse data-flow taint summary, carried across suspend/resume so a\n   * resumed run does not start with an empty ledger that silently un-gates\n   * sinks exposed before the suspend. Structurally matches\n   * `@graphorin/security`'s `TaintLedgerSnapshot` (core takes no security\n   * dependency); only the load-bearing flags are persisted — never the tracked\n   * untrusted text spans.\n   */\n  taintSummary?: RunTaintSummary;\n  /**\n   * AG-19: names of deferred tools promoted by `tool_search` this run, carried\n   * across suspend/resume so discovered tools remain in the per-step catalogue.\n   */\n  promotedTools?: ReadonlyArray<string>;\n  readonly startedAt: string;\n  finishedAt?: string;\n  error?: RunError;\n}\n\n/**\n * Coarse, serializable data-flow taint summary persisted in {@link RunState}\n * across suspend/resume (AG-19). Structurally identical to\n * `@graphorin/security`'s `TaintLedgerSnapshot`; carries no untrusted text.\n *\n * @stable\n */\nexport interface RunTaintSummary {\n  readonly untrustedSeen: boolean;\n  readonly sensitiveSeen: boolean;\n  readonly untrustedSourceKinds: ReadonlyArray<string>;\n}\n\n/**\n * Snapshot helper used by `@graphorin/observability` aggregators to\n * convert the on-disk `usageByModel` shape into the canonical\n * {@link ModelUsage} array. Pure utility — kept in core so consumers\n * do not have to take an observability dependency just to flatten a\n * run-state breakdown.\n *\n * @stable\n */\nexport function flattenUsageByModel(\n  byModel: RunStateUsageByModel | undefined,\n): ReadonlyArray<ModelUsage> {\n  if (byModel === undefined) return [];\n  const out: ModelUsage[] = [];\n  for (const [modelId, entry] of Object.entries(byModel)) {\n    const m: ModelUsage = {\n      modelId,\n      promptTokens: entry.promptTokens,\n      completionTokens: entry.completionTokens,\n      totalTokens: entry.totalTokens,\n      callCount: entry.attemptCount,\n      ...(entry.reasoningTokens !== undefined ? { reasoningTokens: entry.reasoningTokens } : {}),\n      ...(entry.cost !== undefined ? { cost: entry.cost } : {}),\n    };\n    out.push(m);\n  }\n  return out;\n}\n\n/**\n * Failure carried by `RunState.error`. The shape mirrors the wire format\n * used by `agent.error` events.\n *\n * @stable\n */\nexport interface RunError {\n  readonly message: string;\n  readonly code: string;\n  readonly details?: unknown;\n}\n\n/**\n * Per-run dependency / context bag handed to every tool, hook and\n * provider middleware in scope. Generic over the user-defined deps shape.\n *\n * `tracer`, `signal`, `usage` and `state` are always present; everything\n * else is optional.\n *\n * @stable\n */\nexport interface RunContext<TDeps = unknown> {\n  readonly runId: string;\n  readonly sessionId: string;\n  readonly userId?: string;\n  readonly agentId: string;\n  readonly deps: TDeps;\n  readonly tracer: Tracer;\n  readonly signal: AbortSignal;\n  readonly usage: UsageAccumulator;\n  readonly stepNumber: number;\n  readonly messages: ReadonlyArray<Message>;\n  readonly state: RunState;\n}\n"],"mappings":";;;;;;;;;;AAuHA,SAAgB,oBACd,SAC2B;AAC3B,KAAI,YAAY,OAAW,QAAO,EAAE;CACpC,MAAMA,MAAoB,EAAE;AAC5B,MAAK,MAAM,CAAC,SAAS,UAAU,OAAO,QAAQ,QAAQ,EAAE;EACtD,MAAMC,IAAgB;GACpB;GACA,cAAc,MAAM;GACpB,kBAAkB,MAAM;GACxB,aAAa,MAAM;GACnB,WAAW,MAAM;GACjB,GAAI,MAAM,oBAAoB,SAAY,EAAE,iBAAiB,MAAM,iBAAiB,GAAG,EAAE;GACzF,GAAI,MAAM,SAAS,SAAY,EAAE,MAAM,MAAM,MAAM,GAAG,EAAE;GACzD;AACD,MAAI,KAAK,EAAE;;AAEb,QAAO"}

package/dist/types/sensitivity.d.ts

@@ -0,0 +1,35 @@
+//#region src/types/sensitivity.d.ts
+/**
+ * Sensitivity tier for any piece of data flowing through Graphorin.
+ *
+ * - `'public'`   — non-sensitive content; safe for any provider, any sink.
+ * - `'internal'` — default for user-generated content; safe for trusted
+ *   providers (loopback / private-network) but redacted for public-tls
+ *   exporters and replay consumers.
+ * - `'secret'`   — credentials, tokens, encryption keys; only ever stays
+ *   in-process and is never serialized to the wire by default.
+ *
+ * @stable
+ */
+type Sensitivity = 'public' | 'internal' | 'secret';
+/**
+ * Strict ordering used by sensitivity-aware filters
+ * (`record.sensitivity ⊆ provider.acceptsSensitivity`).
+ *
+ * @stable
+ */
+declare const SENSITIVITY_ORDER: readonly Sensitivity[];
+/**
+ * Return `true` iff `record` is allowed to flow to a sink declaring `accepts`.
+ *
+ * Comparison is **subset** semantics: the record's tier must be one of the
+ * tiers in `accepts` (it's not enough for the record's tier to be lower).
+ * That mirrors the way provider `acceptsSensitivity` is declared in the
+ * Graphorin trust matrix.
+ *
+ * @stable
+ */
+declare function acceptsSensitivity(accepts: readonly Sensitivity[], record: Sensitivity): boolean;
+//#endregion
+export { SENSITIVITY_ORDER, Sensitivity, acceptsSensitivity };
+//# sourceMappingURL=sensitivity.d.ts.map

package/dist/types/sensitivity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sensitivity.d.ts","names":[],"sources":["../../src/types/sensitivity.ts"],"sourcesContent":[],"mappings":";;AAYA;AAQA;AAYA;;;;;;;;;KApBY,WAAA;;;;;;;cAQC,4BAA4B;;;;;;;;;;;iBAYzB,kBAAA,mBAAqC,uBAAuB"}

package/dist/types/sensitivity.js

@@ -0,0 +1,29 @@
+//#region src/types/sensitivity.ts
+/**
+* Strict ordering used by sensitivity-aware filters
+* (`record.sensitivity ⊆ provider.acceptsSensitivity`).
+*
+* @stable
+*/
+const SENSITIVITY_ORDER = [
+	"public",
+	"internal",
+	"secret"
+];
+/**
+* Return `true` iff `record` is allowed to flow to a sink declaring `accepts`.
+*
+* Comparison is **subset** semantics: the record's tier must be one of the
+* tiers in `accepts` (it's not enough for the record's tier to be lower).
+* That mirrors the way provider `acceptsSensitivity` is declared in the
+* Graphorin trust matrix.
+*
+* @stable
+*/
+function acceptsSensitivity(accepts, record) {
+	return accepts.includes(record);
+}
+
+//#endregion
+export { SENSITIVITY_ORDER, acceptsSensitivity };
+//# sourceMappingURL=sensitivity.js.map

package/dist/types/sensitivity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sensitivity.js","names":["SENSITIVITY_ORDER: readonly Sensitivity[]"],"sources":["../../src/types/sensitivity.ts"],"sourcesContent":["/**\n * Sensitivity tier for any piece of data flowing through Graphorin.\n *\n * - `'public'`   — non-sensitive content; safe for any provider, any sink.\n * - `'internal'` — default for user-generated content; safe for trusted\n *   providers (loopback / private-network) but redacted for public-tls\n *   exporters and replay consumers.\n * - `'secret'`   — credentials, tokens, encryption keys; only ever stays\n *   in-process and is never serialized to the wire by default.\n *\n * @stable\n */\nexport type Sensitivity = 'public' | 'internal' | 'secret';\n\n/**\n * Strict ordering used by sensitivity-aware filters\n * (`record.sensitivity ⊆ provider.acceptsSensitivity`).\n *\n * @stable\n */\nexport const SENSITIVITY_ORDER: readonly Sensitivity[] = ['public', 'internal', 'secret'] as const;\n\n/**\n * Return `true` iff `record` is allowed to flow to a sink declaring `accepts`.\n *\n * Comparison is **subset** semantics: the record's tier must be one of the\n * tiers in `accepts` (it's not enough for the record's tier to be lower).\n * That mirrors the way provider `acceptsSensitivity` is declared in the\n * Graphorin trust matrix.\n *\n * @stable\n */\nexport function acceptsSensitivity(accepts: readonly Sensitivity[], record: Sensitivity): boolean {\n  return accepts.includes(record);\n}\n"],"mappings":";;;;;;;AAoBA,MAAaA,oBAA4C;CAAC;CAAU;CAAY;CAAS;;;;;;;;;;;AAYzF,SAAgB,mBAAmB,SAAiC,QAA8B;AAChG,QAAO,QAAQ,SAAS,OAAO"}

package/dist/types/session-scope.d.ts

@@ -0,0 +1,22 @@
+//#region src/types/session-scope.d.ts
+/**
+ * Identifies a logical conversational scope: who the user is, which agent
+ * is in charge, and (when known) which session they're inside.
+ *
+ * Used as a parameter to almost every Memory / Sessions API. The agent and
+ * session fields are optional because some scopes are user-wide (e.g.
+ * shared facts attached to a user, not a particular agent).
+ *
+ * @stable
+ */
+interface SessionScope {
+  /** Stable identifier of the user (single-user-per-process by default). */
+  readonly userId: string;
+  /** Identifier of the agent owning the scope, when applicable. */
+  readonly agentId?: string;
+  /** Identifier of the session, when applicable. */
+  readonly sessionId?: string;
+}
+//#endregion
+export { SessionScope };
+//# sourceMappingURL=session-scope.d.ts.map

package/dist/types/session-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-scope.d.ts","names":[],"sources":["../../src/types/session-scope.ts"],"sourcesContent":[],"mappings":";;AAUA;;;;;;;;;UAAiB,YAAA"}

package/dist/types/stop-condition.d.ts

@@ -0,0 +1,62 @@
+import { RunState } from "./run.js";
+
+//#region src/types/stop-condition.d.ts
+
+/**
+ * Predicate consulted by the agent runtime after every step to decide
+ * whether the loop should stop.
+ *
+ * Stop conditions are pure — they look at the current `RunState` and
+ * return a boolean. The runtime never re-orders or short-circuits the
+ * order in which operands of `and` / `or` are evaluated, so users can
+ * rely on the obvious left-to-right semantics.
+ *
+ * @stable
+ */
+interface StopCondition {
+  /** Human-friendly label included in observability spans. */
+  readonly description: string;
+  /** Returns `true` when the run should stop on this state. */
+  readonly check: (state: RunState) => boolean;
+}
+/**
+ * Stop after `n` total steps (`stepNumber >= n`). The default condition
+ * for the agent runtime is `isStepCount(50)`.
+ *
+ * @stable
+ */
+declare function isStepCount(n: number): StopCondition;
+/**
+ * Stop as soon as the most recent assistant message contains a tool call
+ * with the given name.
+ *
+ * @stable
+ */
+declare function hasToolCall(toolName: string): StopCondition;
+/**
+ * Stop when the run reaches a terminal status.
+ *
+ * @stable
+ */
+declare const isTerminal: StopCondition;
+/**
+ * Stop when **any** of the supplied conditions is satisfied.
+ *
+ * @stable
+ */
+declare function or(...conditions: readonly StopCondition[]): StopCondition;
+/**
+ * Stop only when **all** of the supplied conditions are satisfied.
+ *
+ * @stable
+ */
+declare function and(...conditions: readonly StopCondition[]): StopCondition;
+/**
+ * Negate the supplied condition.
+ *
+ * @stable
+ */
+declare function not(condition: StopCondition): StopCondition;
+//#endregion
+export { StopCondition, and, hasToolCall, isStepCount, isTerminal, not, or };
+//# sourceMappingURL=stop-condition.d.ts.map

package/dist/types/stop-condition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stop-condition.d.ts","names":[],"sources":["../../src/types/stop-condition.ts"],"sourcesContent":[],"mappings":";;;;;;AAaA;AAaA;AAgBA;AAyBA;AAWA;AAYA;AAYA;;;UAzFiB,aAAA;;;;0BAIS;;;;;;;;iBASV,WAAA,aAAwB;;;;;;;iBAgBxB,WAAA,oBAA+B;;;;;;cAyBlC,YAAY;;;;;;iBAWT,EAAA,yBAA2B,kBAAkB;;;;;;iBAY7C,GAAA,yBAA4B,kBAAkB;;;;;;iBAY9C,GAAA,YAAe,gBAAgB"}

package/dist/types/stop-condition.js

@@ -0,0 +1,81 @@
+//#region src/types/stop-condition.ts
+/**
+* Stop after `n` total steps (`stepNumber >= n`). The default condition
+* for the agent runtime is `isStepCount(50)`.
+*
+* @stable
+*/
+function isStepCount(n) {
+	if (!Number.isFinite(n) || n <= 0) throw new RangeError(`isStepCount: n must be a positive integer (got ${String(n)})`);
+	return {
+		description: `step >= ${n}`,
+		check: (state) => state.steps.length >= n
+	};
+}
+/**
+* Stop as soon as the most recent assistant message contains a tool call
+* with the given name.
+*
+* @stable
+*/
+function hasToolCall(toolName) {
+	return {
+		description: `tool-call:${toolName}`,
+		check: (state) => {
+			for (let i = state.messages.length - 1; i >= 0; i--) {
+				const msg = state.messages[i];
+				if (msg && msg.role === "assistant") {
+					if (msg.toolCalls?.some((c) => c.toolName === toolName)) return true;
+					return false;
+				}
+			}
+			return false;
+		}
+	};
+}
+/**
+* Stop when the run reaches a terminal status.
+*
+* @stable
+*/
+const isTerminal = {
+	description: "status:terminal",
+	check: (state) => state.status === "completed" || state.status === "failed" || state.status === "aborted"
+};
+/**
+* Stop when **any** of the supplied conditions is satisfied.
+*
+* @stable
+*/
+function or(...conditions) {
+	return {
+		description: `or(${conditions.map((c) => c.description).join(", ")})`,
+		check: (state) => conditions.some((c) => c.check(state))
+	};
+}
+/**
+* Stop only when **all** of the supplied conditions are satisfied.
+*
+* @stable
+*/
+function and(...conditions) {
+	return {
+		description: `and(${conditions.map((c) => c.description).join(", ")})`,
+		check: (state) => conditions.every((c) => c.check(state))
+	};
+}
+/**
+* Negate the supplied condition.
+*
+* @stable
+*/
+function not(condition) {
+	return {
+		description: `not(${condition.description})`,
+		check: (state) => !condition.check(state)
+	};
+}
+
+//#endregion
+export { and, hasToolCall, isStepCount, isTerminal, not, or };
+//# sourceMappingURL=stop-condition.js.map

package/dist/types/stop-condition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stop-condition.js","names":["isTerminal: StopCondition"],"sources":["../../src/types/stop-condition.ts"],"sourcesContent":["import type { RunState } from './run.js';\n\n/**\n * Predicate consulted by the agent runtime after every step to decide\n * whether the loop should stop.\n *\n * Stop conditions are pure — they look at the current `RunState` and\n * return a boolean. The runtime never re-orders or short-circuits the\n * order in which operands of `and` / `or` are evaluated, so users can\n * rely on the obvious left-to-right semantics.\n *\n * @stable\n */\nexport interface StopCondition {\n  /** Human-friendly label included in observability spans. */\n  readonly description: string;\n  /** Returns `true` when the run should stop on this state. */\n  readonly check: (state: RunState) => boolean;\n}\n\n/**\n * Stop after `n` total steps (`stepNumber >= n`). The default condition\n * for the agent runtime is `isStepCount(50)`.\n *\n * @stable\n */\nexport function isStepCount(n: number): StopCondition {\n  if (!Number.isFinite(n) || n <= 0) {\n    throw new RangeError(`isStepCount: n must be a positive integer (got ${String(n)})`);\n  }\n  return {\n    description: `step >= ${n}`,\n    check: (state): boolean => state.steps.length >= n,\n  };\n}\n\n/**\n * Stop as soon as the most recent assistant message contains a tool call\n * with the given name.\n *\n * @stable\n */\nexport function hasToolCall(toolName: string): StopCondition {\n  return {\n    description: `tool-call:${toolName}`,\n    check: (state): boolean => {\n      for (let i = state.messages.length - 1; i >= 0; i--) {\n        const msg = state.messages[i];\n        if (msg && msg.role === 'assistant') {\n          const calls = msg.toolCalls;\n          if (calls?.some((c) => c.toolName === toolName)) {\n            return true;\n          }\n          // First assistant message without the call → not yet matched.\n          return false;\n        }\n      }\n      return false;\n    },\n  };\n}\n\n/**\n * Stop when the run reaches a terminal status.\n *\n * @stable\n */\nexport const isTerminal: StopCondition = {\n  description: 'status:terminal',\n  check: (state): boolean =>\n    state.status === 'completed' || state.status === 'failed' || state.status === 'aborted',\n};\n\n/**\n * Stop when **any** of the supplied conditions is satisfied.\n *\n * @stable\n */\nexport function or(...conditions: readonly StopCondition[]): StopCondition {\n  return {\n    description: `or(${conditions.map((c) => c.description).join(', ')})`,\n    check: (state): boolean => conditions.some((c) => c.check(state)),\n  };\n}\n\n/**\n * Stop only when **all** of the supplied conditions are satisfied.\n *\n * @stable\n */\nexport function and(...conditions: readonly StopCondition[]): StopCondition {\n  return {\n    description: `and(${conditions.map((c) => c.description).join(', ')})`,\n    check: (state): boolean => conditions.every((c) => c.check(state)),\n  };\n}\n\n/**\n * Negate the supplied condition.\n *\n * @stable\n */\nexport function not(condition: StopCondition): StopCondition {\n  return {\n    description: `not(${condition.description})`,\n    check: (state): boolean => !condition.check(state),\n  };\n}\n"],"mappings":";;;;;;;AA0BA,SAAgB,YAAY,GAA0B;AACpD,KAAI,CAAC,OAAO,SAAS,EAAE,IAAI,KAAK,EAC9B,OAAM,IAAI,WAAW,kDAAkD,OAAO,EAAE,CAAC,GAAG;AAEtF,QAAO;EACL,aAAa,WAAW;EACxB,QAAQ,UAAmB,MAAM,MAAM,UAAU;EAClD;;;;;;;;AASH,SAAgB,YAAY,UAAiC;AAC3D,QAAO;EACL,aAAa,aAAa;EAC1B,QAAQ,UAAmB;AACzB,QAAK,IAAI,IAAI,MAAM,SAAS,SAAS,GAAG,KAAK,GAAG,KAAK;IACnD,MAAM,MAAM,MAAM,SAAS;AAC3B,QAAI,OAAO,IAAI,SAAS,aAAa;AAEnC,SADc,IAAI,WACP,MAAM,MAAM,EAAE,aAAa,SAAS,CAC7C,QAAO;AAGT,YAAO;;;AAGX,UAAO;;EAEV;;;;;;;AAQH,MAAaA,aAA4B;CACvC,aAAa;CACb,QAAQ,UACN,MAAM,WAAW,eAAe,MAAM,WAAW,YAAY,MAAM,WAAW;CACjF;;;;;;AAOD,SAAgB,GAAG,GAAG,YAAqD;AACzE,QAAO;EACL,aAAa,MAAM,WAAW,KAAK,MAAM,EAAE,YAAY,CAAC,KAAK,KAAK,CAAC;EACnE,QAAQ,UAAmB,WAAW,MAAM,MAAM,EAAE,MAAM,MAAM,CAAC;EAClE;;;;;;;AAQH,SAAgB,IAAI,GAAG,YAAqD;AAC1E,QAAO;EACL,aAAa,OAAO,WAAW,KAAK,MAAM,EAAE,YAAY,CAAC,KAAK,KAAK,CAAC;EACpE,QAAQ,UAAmB,WAAW,OAAO,MAAM,EAAE,MAAM,MAAM,CAAC;EACnE;;;;;;;AAQH,SAAgB,IAAI,WAAyC;AAC3D,QAAO;EACL,aAAa,OAAO,UAAU,YAAY;EAC1C,QAAQ,UAAmB,CAAC,UAAU,MAAM,MAAM;EACnD"}

package/dist/types/tool-call.d.ts

@@ -0,0 +1,27 @@
+//#region src/types/tool-call.d.ts
+/**
+ * The {@link ToolCall} leaf type lives in its own module so that
+ * `message.ts` (which references `ToolCall`) and `tool.ts` (which
+ * references `MessageContent`) can both depend on it without forming a
+ * circular import. `tool.ts` re-exports `ToolCall` for backwards
+ * compatibility, so external import paths are unchanged.
+ *
+ * @packageDocumentation
+ */
+/**
+ * A single tool invocation the model requested, normalised by the
+ * provider layer and handed to the tool executor for parallel dispatch.
+ *
+ * @stable
+ */
+interface ToolCall {
+  /** Stable identifier the model uses to correlate input and output. */
+  readonly toolCallId: string;
+  /** Tool name as registered in the `ToolRegistry`. */
+  readonly toolName: string;
+  /** Validated input matching the tool's `inputSchema`. */
+  readonly args: unknown;
+}
+//#endregion
+export { ToolCall };
+//# sourceMappingURL=tool-call.d.ts.map

package/dist/types/tool-call.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-call.d.ts","names":[],"sources":["../../src/types/tool-call.ts"],"sourcesContent":[],"mappings":";;AAgBA;;;;;;;;;;;;;;UAAiB,QAAA"}

package/dist/types/tool.d.ts

@@ -0,0 +1,260 @@
+import { ToolCall } from "./tool-call.js";
+import { MessageContent } from "./message.js";
+
+//#region src/types/tool.d.ts
+
+/**
+ * Sandbox isolation level requested for a tool's `execute` method.
+ *
+ * The exact semantics live in `@graphorin/security`; downstream packages
+ * type their config field as `SandboxPolicy` so they don't take a security
+ * dependency just to type their inputs.
+ *
+ * @stable
+ */
+type SandboxPolicy = 'none' | 'sandboxed' | 'isolated' | 'docker';
+/**
+ * Memory-modification guard tier requested for a tool's `execute` method.
+ *
+ * Mirrors the tier classification consumed by `@graphorin/security`'s
+ * memory-modification guard so downstream packages can type their tool
+ * metadata against this discriminator without a hard dependency on the
+ * security package.
+ *
+ * - `'pure'`                     — no side effects of any kind.
+ * - `'side-effecting-no-memory'` — observable side effects outside of
+ *   the framework's memory tiers (e.g. external HTTP).
+ * - `'memory-aware'`             — mutates the framework's memory
+ *   tiers via the sanctioned `ctx.memory.*` surface only.
+ * - `'unknown'`                  — no declaration; the runtime applies
+ *   the audit-only baseline.
+ * - `'untrusted'`                — third-party / untrusted skill code;
+ *   the runtime forces the strictest snapshot policy.
+ *
+ * @stable
+ */
+type MemoryGuardTier = 'pure' | 'side-effecting-no-memory' | 'memory-aware' | 'unknown' | 'untrusted';
+/**
+ * Side-effect classification declared by a tool author.
+ *
+ * Surfaced uniformly by the tool dispatcher, downstream session
+ * cassette layers, retry middleware, and approval-policy derivations.
+ *
+ * - `'pure'`              — deterministic; same `(input, ctx)` always
+ *   yields the same output; no I/O of any kind.
+ * - `'read-only'`         — queries external systems but never
+ *   mutates them (e.g. database SELECT, HTTP GET).
+ * - `'side-effecting'`    — mutates state inside the agent's logical
+ *   boundary (e.g. memory writes, cache writes).
+ * - `'external-stateful'` — mutates state outside the agent's
+ *   boundary that other systems can observe (e.g. issue creation,
+ *   message dispatch, payment).
+ *
+ * @stable
+ */
+type SideEffectClass = 'pure' | 'read-only' | 'side-effecting' | 'external-stateful';
+/**
+ * Inbound prompt-injection sanitization policy applied to a tool's
+ * result body before it reaches the conversation history.
+ *
+ * - `'pass-through'`              — no scan; bytes-equal forwarding
+ *   (the trusted-built-in default).
+ * - `'detect-and-flag'`           — scan; emit a flag span attribute
+ *   + audit row but do not modify the body.
+ * - `'detect-and-strip'`          — replace each match with the
+ *   `[REDACTED:imperative-pattern]` literal token.
+ * - `'detect-and-wrap'`           — wrap the body in the
+ *   `<<<untrusted_content>>>` envelope without stripping matches.
+ * - `'detect-and-strip-and-wrap'` — both strip matches and wrap the
+ *   resulting body (the untrusted-source default).
+ *
+ * @stable
+ */
+type InboundSanitizationPolicy = 'pass-through' | 'detect-and-flag' | 'detect-and-strip' | 'detect-and-wrap' | 'detect-and-strip-and-wrap';
+/**
+ * Result-envelope truncation strategy applied to a tool's assembled
+ * output before it reaches the conversation history.
+ *
+ * - `'middle'`         — keep head and tail; insert annotation in the
+ *   middle (the default).
+ * - `'tail'`           — keep the tail; insert annotation at the
+ *   head.
+ * - `'spill-to-file'`  — keep the head; spill the un-truncated body
+ *   to a per-run artifact file; insert annotation with the artifact
+ *   path.
+ * - `'summarize'`      — invoke the agent's configured summarizer
+ *   and replace the body with the summary.
+ *
+ * @stable
+ */
+type TruncationStrategy = 'middle' | 'tail' | 'spill-to-file' | 'summarize';
+/**
+ * Trust class assigned to a registered tool. The class is computed at
+ * registration time from the registration source and the declared
+ * sandbox policy; downstream layers (sanitization, audit) read the
+ * class to pick the right default policy.
+ *
+ * @stable
+ */
+type ToolTrustClass = 'first-party-built-in' | 'first-party-user-defined' | 'skill-trusted' | 'skill-untrusted' | 'mcp-derived' | 'web-search';
+/**
+ * Source descriptor attached to a `Tool` registration. Mirrors the
+ * registration-time provenance the dispatcher uses to derive the
+ * trust class and to compute the four collision audit row kinds.
+ *
+ * @stable
+ */
+type ToolSource = {
+  readonly kind: 'first-party';
+} | {
+  readonly kind: 'built-in';
+  readonly subsystem: string;
+} | {
+  readonly kind: 'skill';
+  readonly skillName: string;
+  readonly trustLevel: 'trusted' | 'untrusted';
+} | {
+  readonly kind: 'mcp';
+  readonly serverIdentity: string;
+} | {
+  readonly kind: 'web-search';
+  readonly providerName: string;
+};
+/**
+ * Single chunk of streamed tool content. Streaming-hint tools emit one
+ * chunk per `ctx.streamContent(...)` call; the executor concatenates
+ * the chunks into the assembled `output` per the buffer-becomes-output
+ * discipline.
+ *
+ * @stable
+ */
+type ContentChunk = {
+  readonly kind: 'text';
+  readonly text: string;
+} | {
+  readonly kind: 'json-delta';
+  readonly path: string;
+  readonly value: unknown;
+} | {
+  readonly kind: 'image';
+  readonly data: Uint8Array;
+  readonly mediaType: string;
+};
+/**
+ * The successful outcome of a tool invocation, returned to the model.
+ *
+ * @stable
+ */
+interface ToolResult<TOutput = unknown> {
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly output: TOutput;
+  /**
+   * Optional content parts to append to the conversation (images, files,
+   * etc.). Tools that emit binary results use this field instead of trying
+   * to encode the binary into `output`.
+   */
+  readonly contentParts?: readonly MessageContent[];
+  readonly durationMs: number;
+  /**
+   * Set when the tool's output was large enough to be stored behind a
+   * handle (the `'spill-to-file'` truncation strategy, or — later — an MCP
+   * `resource_link`) instead of being inlined in full. The runtime inlines
+   * only the bounded {@link ResultHandle.preview} and lets the model fetch
+   * the rest on demand via the built-in `read_result` tool. Absent for
+   * results that were inlined directly.
+   */
+  readonly resultHandle?: ResultHandle;
+}
+/**
+ * An opaque, run-scoped reference to a large tool result that was stored
+ * out of the conversation buffer rather than inlined in full. The agent
+ * inlines {@link preview} (plus a retrieval hint) and registers the
+ * built-in `read_result` tool so the model can page through the full
+ * artifact behind {@link uri} on demand — keeping large results out of the
+ * context window (P1-4).
+ *
+ * @stable
+ */
+interface ResultHandle {
+  /**
+   * Opaque, run-scoped URI — e.g. `graphorin-spill:<runId>/<toolCallId>.json`
+   * for a spill artifact. Never a raw filesystem path: the reader resolves
+   * it within the configured artifact root, so the model cannot use it to
+   * read arbitrary files.
+   */
+  readonly uri: string;
+  /** Backing store kind. `'spill-file'` today; `'resource-link'` is reserved for MCP (WI-13). */
+  readonly kind: 'spill-file' | 'resource-link';
+  /** A bounded preview of the full body (already inlined alongside the handle). */
+  readonly preview: string;
+  /** Total byte size of the full stored artifact, when known. */
+  readonly bytes?: number;
+  /** MIME type of the stored artifact, when known. */
+  readonly mediaType?: string;
+  /**
+   * Trust class of the tool that PRODUCED the stored body (TL-6).
+   * `read_result` re-applies inbound sanitization and dataflow
+   * provenance by this class, so an untrusted spill cannot launder to
+   * trusted through the built-in reader.
+   */
+  readonly producerTrustClass?: ToolTrustClass;
+}
+/**
+ * Discriminator used by `ToolError.kind`. The list is exhaustive: any new
+ * kind must extend the union here and every `assertNever` switch.
+ *
+ * @stable
+ */
+type ToolErrorKind = 'approval_denied' | 'sandbox_violation' | 'timeout' | 'invalid_input' | 'invalid_output' | 'execution_failed' | 'unknown_tool' | 'aborted' | 'inbound_sanitization_blocked' | 'dataflow_policy_blocked' | 'rate_limited';
+/**
+ * The unsuccessful outcome of a tool invocation. The model sees a textual
+ * representation of `message`; the runtime sees the typed shape.
+ *
+ * @stable
+ */
+interface ToolError {
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly kind: ToolErrorKind;
+  readonly message: string;
+  /** Optional underlying cause (chained errors). */
+  readonly cause?: unknown;
+  /** Optional remediation hint for human readers. */
+  readonly hint?: string;
+}
+/**
+ * Either a `ToolResult` or a `ToolError`. The runtime always returns one
+ * of the two — there is no implicit "tool fell through" outcome.
+ *
+ * @stable
+ */
+type ToolOutcome<TOutput = unknown> = ToolResult<TOutput> | ToolError;
+/**
+ * Pending approval bookkeeping: a tool that needed human confirmation
+ * before execution. Stored on `RunState.pendingApprovals` until the
+ * caller resumes the run with a granted/denied decision.
+ *
+ * @stable
+ */
+interface ToolApproval {
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly args: unknown;
+  readonly reason?: string;
+  readonly requestedAt: string;
+}
+/**
+ * A `ToolCall` paired with its outcome and execution metadata. Captured
+ * on `RunState.completedToolCalls` after a successful or failed run.
+ *
+ * @stable
+ */
+interface CompletedToolCall<TOutput = unknown> {
+  readonly call: ToolCall;
+  readonly outcome: ToolOutcome<TOutput>;
+  readonly stepNumber: number;
+}
+//#endregion
+export { CompletedToolCall, ContentChunk, InboundSanitizationPolicy, MemoryGuardTier, ResultHandle, SandboxPolicy, SideEffectClass, ToolApproval, ToolError, ToolErrorKind, ToolOutcome, ToolResult, ToolSource, ToolTrustClass, TruncationStrategy };
+//# sourceMappingURL=tool.d.ts.map

package/dist/types/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","names":[],"sources":["../../src/types/tool.ts"],"sourcesContent":[],"mappings":";;;;;;;;AAWA;AAsBA;AAyBA;AAmBA;AAuBA;AAUA;AAeY,KAlHA,aAAA,GAkHU,MAAA,GAAA,WAAA,GAAA,UAAA,GAAA,QAAA;AAmBtB;AAgBA;;;;;AAgCA;AA+BA;AAmBA;AAiBA;;;;;AASA;AAcA;;;;;KAzPY,eAAA;;;;;;;;;;;;;;;;;;;KAyBA,eAAA;;;;;;;;;;;;;;;;;;KAmBA,yBAAA;;;;;;;;;;;;;;;;;KAuBA,kBAAA;;;;;;;;;KAUA,cAAA;;;;;;;;KAeA,UAAA;;;;;;;;;;;;;;;;;;;;;;;;KAmBA,YAAA;;;;;;;;;iBAGiC;;;;;;;;UAa5B;;;mBAGE;;;;;;mCAAO,cAAA;;;;;;;;;;0BAgBA;;;;;;;;;;;;UAaT,YAAA;;;;;;;;;;;;;;;;;;;;;;gCAsBe;;;;;;;;KASpB,aAAA;;;;;;;UAmBK,SAAA;;;iBAGA;;;;;;;;;;;;;KAcL,iCAAiC,WAAW,WAAW;;;;;;;;UASlD,YAAA;;;;;;;;;;;;;UAcA;iBACA;oBACG,YAAY"}