@jangts/agent-core 0.3.5 → 0.5.0

package/dist/esm/structs/capabilities/model.d.ts

@@ -5,18 +5,42 @@
  * host value. Registration snapshots the schema and pins the resolver, so a request can project a
  * sealed subset without cloning handlers.
  *
- * Exports: `ModelCapability`, `ModelCapabilityRegistration`, `RegisteredModelCapability`,
- * `ModelSelection`, `ModelCapabilitySource`, `ModelCapabilityCatalog`.
+ * Exports: `ModelTool`, `ModelToolRegistration`, `RegisteredModelTool`,
+ * `ModelSelection`, `ModelToolSource`, `ModelToolCatalog`.
  */
 import type { SchemaAdapter, ReadonlyCatalog } from '../common.js';
-/** One selectable model operation. */
-export interface ModelCapability<Input = unknown, Output = Input> {
+/** A model proposal, not an authorization or execution receipt. */
+export interface ToolProposal {
+    readonly toolId: string;
+    readonly input: unknown;
+}
+/** Read-only host data without changing explicit any/unknown erasure into an object constraint. */
+export type ToolContext<Context> = unknown extends Context ? Context : Readonly<Context>;
+/** Demand-facing hints attached to one Tool; no independent identity is created. */
+export interface IntentOptions<Context> {
+    /** Optional demand-facing description; otherwise the tool description is reused. */
+    readonly description?: string;
+    /** Synchronous participation predicate. */
+    readonly when?: (context: ToolContext<Context>) => boolean;
+    /** Allowed continuation delegates, not an execution sequence. */
+    readonly delegates?: readonly string[];
+}
+/** Demand-discovery metadata; it has no identity independent of its tool. */
+export type AsIntent<Context> = true | string | ((context: ToolContext<Context>) => boolean) | IntentOptions<Context>;
+/** Activation is independent of participation in demand discovery. */
+export type ToolCondition<Context> = boolean | ((context: ToolContext<Context>) => boolean);
+/** Common selectable model interface; resolution proposes a value without business execution. */
+export interface ModelTool<Input = unknown, Output = Input, Context = any> {
     /** Unique id within its registry; never blank. */
     readonly id: string;
     /** Model-visible description explaining when the capability applies. */
     readonly description: string;
     /** Schema describing the arguments; must be an object schema. */
     readonly inputSchema: SchemaAdapter<Input>;
+    /** Omitted means active. Authorization remains a separate execution boundary. */
+    readonly active?: ToolCondition<Context>;
+    /** Omitted means this tool is not advertised by withIntent(). */
+    readonly asIntent?: AsIntent<Context>;
     /**
      * Converts validated arguments into the value handed back to the caller.
      *
@@ -27,9 +51,11 @@ export interface ModelCapability<Input = unknown, Output = Input> {
     }>): Output;
 }
 /** Registration form: input typing is erased, output typing is preserved. */
-export type ModelCapabilityRegistration<Output = unknown> = ModelCapability<any, Output>;
+export type ModelToolRegistration<Output = unknown> = Omit<ModelTool<any, Output>, 'resolve'> & {
+    readonly resolve?: ModelTool<any, Output>['resolve'];
+};
 /** Frozen snapshot stored by a registry after schema validation. */
-export type RegisteredModelCapability<Output = unknown> = Readonly<ModelCapability<unknown, Output>>;
+export type RegisteredModelTool<Output = unknown> = Readonly<ModelTool<unknown, Output>>;
 /** A model's chosen capability together with its parsed arguments. */
 export type ModelSelection = {
     /** Arguments exactly as produced by the model, before schema parsing. */
@@ -41,15 +67,20 @@ export type ModelSelection = {
         argumentChars: number;
     };
     /** Capability the selection resolved to. */
-    readonly capabilityId: string;
+    readonly toolId: string;
 };
-/** Minimal source a stage needs: enumerate capabilities and resolve one selection. */
-export interface ModelCapabilitySource<Output = unknown> {
-    values(): IterableIterator<RegisteredModelCapability<Output>>;
+/** Minimal source a stage needs: enumerate tools and resolve one selection. */
+export interface ModelToolSource<Output = unknown> {
+    values(): IterableIterator<RegisteredModelTool<Output>>;
     /** Resolves one selection; throws when the capability is absent from this source. */
     resolve(selection: ModelSelection, context: Readonly<{
         stageId: string;
     }>): Output;
 }
 /** A compiled entity catalog also supports the minimal stage source contract. */
-export type ModelCapabilityCatalog<Output = unknown> = ReadonlyCatalog<RegisteredModelCapability<Output>> & ModelCapabilitySource<Output>;
+export type ModelToolCatalog<Output = unknown> = ReadonlyCatalog<RegisteredModelTool<Output>> & ModelToolSource<Output> & {
+    /** Explicit selection, optionally filtered against a host context. */
+    select(ids: readonly string[], context?: unknown): ModelToolCatalog<Output>;
+    /** Demand-facing active tools; no workflow node or invocation is implied. */
+    withIntent(context: unknown): ModelToolCatalog<Output>;
+};

package/dist/esm/structs/capabilities/tools.d.ts

@@ -5,7 +5,7 @@
  * registry binds an App context, validates input/output at the boundary and produces receipts, so
  * individual tools never handle transportation, budget accounting or event emission.
  *
- * Exports: `ToolDefinition`, `ToolExecutionContext`, `ExecutableTool`, `RegisteredTool`,
+ * Exports: `ToolDefinition`, `ToolExecutionContext`, `ErasedTool`, `RegisteredTool`,
  * `ToolExecutionEvent`, `ToolRegistryPorts`, `ToolInvocationRequest`, `ToolRegistryOptions`.
  */
 import type { InvocationMetadata } from '../invocation.js';
@@ -13,8 +13,9 @@ import type { ExecutionContext, MaybePromise, OperationContext, SchemaAdapter }
 import type { DiagnosticContext } from '../diagnostics.js';
 import type { RegistrationProjection } from '../../utils/registration.js';
 import type { NodeReportingContext } from '../debug.js';
+import type { ModelTool, ToolProposal } from './model.js';
 /** One registered tool, typed by its input, output, host context and id literal. */
-export interface ToolDefinition<Input = unknown, Output = unknown, App = unknown, Id extends string = string> {
+export interface ExecutableTool<Input = unknown, Output = unknown, App = unknown, Id extends string = string> extends ModelTool<Input, ToolProposal, App> {
     /** Stable id; also the name the model calls. */
     readonly id: Id;
     /** Declared grouping used by registries and documentation; not an authorization boundary. */
@@ -27,13 +28,19 @@ export interface ToolDefinition<Input = unknown, Output = unknown, App = unknown
     authorize(input: Input, context: OperationContext<App>): MaybePromise<void>;
     /** Executes the already-authorized input; must not repeat authorization decisions. */
     execute(input: Input, context: OperationContext<App> & import('../debug.js').NodeReportingContext): MaybePromise<Output>;
-    /** Optional reporting hook that turns the result into self-reported sub-steps. */
-    debugSteps?(result: Output, context: import('../debug.js').NodeReportingContext): import('../debug.js').SubFlowLogger;
+    /** Optional result hook; writes through context.createSubFlowLogger() are recorded immediately. */
+    debugSteps?(result: Output, context: import('../debug.js').NodeReportingContext): void;
     /** Validates untrusted output (for example a cached replay) before it is returned. */
     parseOutput(value: unknown): Output;
 }
+/** Configuration form; Support supplies the identity resolver when omitted. */
+export type ToolDefinition<Input = unknown, Output = unknown, App = unknown, Id extends string = string> = Omit<ExecutableTool<Input, Output, App, Id>, 'resolve'> & {
+    readonly resolve?: ExecutableTool<Input, Output, App, Id>['resolve'];
+};
 /** Execution facts handed to a tool for one invocation. */
 export interface ToolExecutionContext extends ExecutionContext, NodeReportingContext {
+    /** Delegate bound by Core to this actual invocation. */
+    readonly logger?: import('../debug.js').ScopedSubFlowLogger;
     /** Diagnostic scope of the invocation, when recording is enabled. */
     readonly diagnostics?: DiagnosticContext;
     /** Declared execution discipline; mirrors whether the registry accepted an async tool. */
@@ -44,18 +51,18 @@ export interface ToolExecutionContext extends ExecutionContext, NodeReportingCon
     readonly signal: AbortSignal;
 }
 /** Type-erased tool shape the registry executes after parsing at the boundary. */
-export interface ExecutableTool {
+export interface ErasedTool {
     readonly id: string;
     readonly kind: string;
     /** Optional here because the erased view does not require model-facing prose. */
     readonly description?: string;
-    readonly debugSteps?: (result: unknown, context: NodeReportingContext) => import('../debug.js').SubFlowLogger;
+    readonly debugSteps?: (result: unknown, context: NodeReportingContext) => void;
     parseInput(value: unknown): unknown;
     parseOutput(value: unknown): unknown;
     execute(input: unknown, context: ToolExecutionContext): unknown;
 }
 /** Registered snapshot: public data is retained, implementation helpers are not a contract. */
-export type RegisteredTool<Tool extends ExecutableTool = ExecutableTool> = RegistrationProjection<Tool, ExecutableTool>;
+export type RegisteredTool<Tool extends ErasedTool = ErasedTool> = RegistrationProjection<Tool, ErasedTool>;
 /** Fact emitted when one tool call settles, correlated by `invocationId`. */
 export interface ToolExecutionEvent<Kind extends string = string> extends InvocationMetadata {
     toolId: string;
@@ -79,6 +86,8 @@ export interface ToolRegistryPorts {
 }
 /** One invocation request; the registry supplies signal and diagnostics when omitted. */
 export interface ToolInvocationRequest<Id extends string = string> {
+    /** Explicit recorder for this call, also available to its handler for deliberate use. */
+    readonly logger?: import('../debug.js').SubFlowLogger;
     readonly toolId: Id;
     /** Raw model arguments; parsed by the tool's input schema before authorization. */
     readonly input: unknown;

package/dist/esm/structs/common.d.ts

@@ -93,6 +93,8 @@ export interface ExecutionOptions {
 }
 /** Required execution facts available inside a running call. */
 export interface ExecutionContext {
+    /** Explicit optional recorder for this operation; never inferred from diagnostics. */
+    readonly logger?: import('./debug.js').SubFlowLog;
     /** Non-optional cancellation signal; never `undefined` once execution has started. */
     readonly signal: AbortSignal;
     /** Diagnostic scope of the enclosing call, when recording is enabled. */
@@ -105,7 +107,7 @@ export interface ExecutionContext {
  * it as opaque and must not depend on application-specific fields.
  */
 export interface OperationContext<App = unknown> extends ExecutionContext {
-    readonly app: Readonly<App>;
+    readonly app: unknown extends App ? App : Readonly<App>;
 }
 /**
  * One search result.

package/dist/esm/structs/debug.d.ts

@@ -55,12 +55,18 @@ export declare const reportedStepStatuses: readonly (keyof typeof reportedStepSt
 export type ReportedStepStatus = keyof typeof reportedStepStatusCatalog;
 /** One step as reported by a node; fields beyond identity are optional detail. */
 export interface ReportedStep {
-    /** Step identity, unique within one node visit. */
+    /** App-defined business log type; never a write/fix operation enum. */
+    readonly type?: string;
+    /** Logical subnode grouping within this node visit; independent of individual log ids. */
+    readonly subnodeId?: string;
+    /** Log record identity, unique within one node visit; not a subnode id. */
     readonly stepId: string;
     /** Reported parent step, forming a tree; absent for a top-level step. */
     readonly parentStepId?: string;
     /** Self-reported reference only; never a workflow dispatch identity. */
     readonly relatedDefinitionId?: string;
+    /** Real model/tool invocation identity, kept separate from the node-local subnode id. */
+    readonly relatedInvocationId?: string;
     /** Short reported label. */
     readonly name: string;
     /** Reported step kind (for example a tool or model call); free-form and node-owned. */
@@ -88,7 +94,11 @@ export type SubFlowValue = null | boolean | number | string | readonly SubFlowVa
 export interface RecordedSubStep extends ReportedStep {
     /** Historical marker: only self-reported steps are recorded. */
     readonly origin: 'reported';
-    /** One-based write order within the node visit. */
+    /** Append-only logging operation, separate from the App-owned business type. */
+    readonly operation?: 'write' | 'fix';
+    /** Original write record revised by this fix; fixes have their own stepId. */
+    readonly targetStepId?: string;
+    /** One-based append order within the node visit, including every fix. */
     readonly sequence: number;
     /** Optional only for historical records produced before the logger contract. */
     readonly createdAtMs?: number;
@@ -98,10 +108,14 @@ export interface RecordedSubStep extends ReportedStep {
     readonly payload?: Readonly<Record<string, SubFlowValue>>;
 }
 /** Input accepted by `write`; the logger assigns the step id and sequence. */
-export interface SubFlowStepInput extends Omit<ReportedStep, 'stepId'> {
+export interface SubFlowStepInput extends Omit<ReportedStep, 'stepId' | 'kind'> {
+    /** Optional family classification; defaults to the custom type when omitted. */
+    readonly kind?: string;
     readonly payload?: Readonly<Record<string, SubFlowValue>>;
 }
-/** Fields a later `fix` may change on an already written step. */
+/** Scoped writes cannot supply or override the identity bound by their delegate. */
+export type ScopedSubFlowStepInput = Omit<SubFlowStepInput, 'subnodeId'>;
+/** Explicit revision whitelist: identity, grouping and business type are never patchable. */
 export interface SubFlowStepFix {
     readonly status?: ReportedStepStatus;
     readonly usedModel?: boolean;
@@ -112,31 +126,34 @@ export interface SubFlowStepFix {
     /** Fill missing result fields; existing facts cannot be replaced. */
     readonly payload?: Readonly<Record<string, SubFlowValue>>;
 }
-declare const subFlowLoggerBrand: unique symbol;
-/** Execution-owned instance. Obtain it from the active node/tool context. */
-export interface SubFlowLogger {
-    /** Brand makes structural lookalikes incompatible with the recorder's own instance. */
-    readonly [subFlowLoggerBrand]: true;
-    /** Appends one step and returns its assigned step id. */
-    write(input: SubFlowStepInput): string;
-    /** Applies a partial update; illegal status transitions and replacements are rejected. */
-    fix(stepId: string, patch: SubFlowStepFix): void;
-    /** Snapshot of the steps recorded so far, in write order. */
+/** Common read/write surface for both independently implemented logger classes. */
+export interface SubFlowLog {
+    write(input: ScopedSubFlowStepInput): string | -1;
+    fix(stepId: string | -1, patch: SubFlowStepFix): boolean;
+    /** Both logger classes return the same complete immutable ledger. */
     readAll(): readonly Readonly<RecordedSubStep>[];
 }
+/** Nominal classes: only the full logger is accepted by native invocation requests. */
+export type { SubFlowLogger, ScopedSubFlowLogger } from '../diagnostics/sub-flow.js';
+import type { SubFlowLogger } from '../diagnostics/sub-flow.js';
 /** Reporting surface handed to a node or tool for the duration of one visit. */
 export interface NodeReportingContext {
     /** Reports progress for the active node; Core supplies the execution identity. */
     report(update: import('./execution/workflow.js').WorkflowNodeReport): void;
-    /** One logger per node visit; repeated calls return the same instance. */
+    /** Bound to this context and owned by runtime; repeated calls in one visit return the same instance. */
     createSubFlowLogger(): SubFlowLogger;
 }
 /** Compact progress notification emitted for each accepted sub-step write or fix. */
 export interface SubStepProgress {
+    readonly relatedInvocationId?: string;
     readonly operation: 'write' | 'fix';
-    /** Step the operation applied to. */
+    readonly type?: string;
+    readonly subnodeId?: string;
+    /** Original write record when this operation is a fix. */
+    readonly targetStepId?: string;
+    /** Unique id of this append-only record. */
     readonly stepId: string;
-    /** Write sequence of that step within the node visit. */
+    /** Append sequence of this record within the node visit, including every fix. */
     readonly sequence: number;
     /** Revision after the operation; `write` starts at 1. */
     readonly revision: number;
@@ -151,7 +168,6 @@ export interface SubStepProgress {
 export interface DebugStepsOutput {
     /** Model use reported by this handler; omitted when unknown. */
     readonly usedModel?: boolean;
-    /** Accessor invoked at emit time so recording can be skipped when disabled. */
-    readonly subSteps?: () => SubFlowLogger | undefined;
+    /** Runtime-owned immutable snapshot, committed when a logger writes or fixes a step. */
+    readonly recordedSubSteps?: readonly Readonly<RecordedSubStep>[];
 }
-export {};

package/dist/esm/structs/execution/workflow-views.d.ts

@@ -0,0 +1,123 @@
+/** Serializable topology and observed execution contracts; layout belongs to consumers. */
+import type { CoreDiagnosticRecord } from '../diagnostics.js';
+import type { RecordedSubStep, SubFlowValue } from '../debug.js';
+import type { WorkflowEvent } from './workflow.js';
+/** Pure registered topology; routes sharing a target share an edge within one kind. */
+export interface WorkflowGraph {
+    readonly schemaVersion: 1;
+    readonly workflowId: string;
+    readonly revision?: string;
+    readonly entryNodeId: string;
+    readonly nodes: readonly WorkflowGraphNode[];
+    readonly edges: readonly WorkflowGraphEdge[];
+}
+/** Node metadata and derived incident edges, without executable callbacks. */
+export interface WorkflowGraphNode {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly order: number;
+    readonly startsRound: boolean;
+    readonly requires: readonly string[];
+    readonly provides: readonly string[];
+    readonly routes: readonly WorkflowGraphRoute[];
+    readonly incomingEdgeIds: readonly string[];
+    readonly outgoingEdgeIds: readonly string[];
+}
+/** Declaration order is retained even when multiple routes share a topology edge. */
+export interface WorkflowGraphRoute {
+    readonly order: number;
+    readonly routeId?: string;
+    readonly description?: string;
+    readonly conditional: boolean;
+    readonly conditionId?: string;
+    readonly edgeId: string;
+}
+/** Completion has no target node; recovery edges remain distinct from normal edges. */
+export interface WorkflowGraphEdge {
+    readonly id: string;
+    readonly kind: 'transition' | 'error' | 'complete';
+    readonly sourceNodeId: string;
+    readonly targetNodeId?: string;
+    readonly routeOrders: readonly number[];
+    readonly errorRouteId?: string;
+}
+/** Capture completeness is independent of whether diagnostic content was included. */
+export interface WorkflowChainCoverage {
+    readonly complete: boolean | 'unknown';
+    readonly content: 'included' | 'omitted' | 'mixed' | 'unknown';
+    readonly issues: readonly {
+        readonly code: string;
+        readonly spanId?: string;
+        readonly eventId?: string;
+        readonly count?: number;
+    }[];
+}
+/** App resolves authorization, retention, pagination and storage paths before returning. */
+export type WorkflowChainSource = (runId: string) => Promise<{
+    readonly events: readonly CoreDiagnosticRecord[];
+    readonly coverage: WorkflowChainCoverage;
+}>;
+/** Observed visits, never merged by static node id or synthesized from adjacency. */
+export interface WorkflowChain {
+    readonly schemaVersion: 1;
+    readonly workflowId: string;
+    readonly runId: string;
+    readonly nodes: readonly WorkflowChainNode[];
+    readonly transitions: readonly WorkflowChainTransition[];
+    readonly coverage: WorkflowChainCoverage;
+}
+/** Historical subflow snapshots may omit recorder fields or descriptive content. */
+export type WorkflowSubflowRecord = Omit<RecordedSubStep, 'name' | 'kind'> & {
+    readonly name?: string;
+    readonly kind?: string;
+    readonly sourceEventId?: string;
+    readonly producerSequence?: number;
+};
+/** A single node visit, with flat ordered subflow records including every independent fix. */
+export interface WorkflowChainNode {
+    readonly spanId: string;
+    readonly nodeId: string;
+    readonly workflowInvocationId?: string;
+    readonly definitionRevision?: string;
+    readonly name?: string;
+    readonly description?: string;
+    readonly kind?: string;
+    readonly roundIndex?: number;
+    readonly firstEventSequence: number;
+    readonly lastEventSequence: number;
+    readonly enteredAtMs?: number;
+    readonly endedAtMs?: number;
+    readonly durationMs?: number;
+    readonly status: 'running' | 'success' | 'error' | 'cancelled' | 'unknown';
+    readonly usedModel?: boolean;
+    readonly events: readonly WorkflowChainNodeEvent[];
+    readonly subflow: readonly WorkflowSubflowRecord[];
+}
+/** Node-local lifecycle facts; payload remains subject to the source's content policy. */
+export interface WorkflowChainNodeEvent {
+    readonly eventId: string;
+    readonly producerSequence: number;
+    readonly occurredAtMs: number;
+    readonly type: WorkflowEvent['type'] | 'progress';
+    readonly phase?: WorkflowEvent['phase'];
+    readonly routeId?: string;
+    readonly conditionId?: string;
+    readonly errorCode?: string;
+    readonly errorEventId?: string;
+    readonly payload?: SubFlowValue;
+}
+/** Actual handoff evidence; a target span does not prove its enter event was captured. */
+export interface WorkflowChainTransition {
+    readonly eventId: string;
+    readonly producerSequence: number;
+    readonly occurredAtMs: number;
+    readonly type: 'transition' | 'complete';
+    readonly sourceSpanId: string;
+    readonly targetSpanId?: string;
+    readonly targetNodeId?: string;
+    readonly routeOrder?: number;
+    readonly routeId?: string;
+    readonly conditionId?: string;
+    readonly errorEventId?: string;
+}

package/dist/esm/structs/execution/workflow.d.ts

@@ -1,3 +1,4 @@
+import type { WorkflowChainSource } from './workflow-views.js';
 /**
  * Workflow contract: a state graph whose nodes report their own use of model and tools.
  *
@@ -66,8 +67,6 @@ export interface WorkflowNodeReport {
     readonly usedModel?: boolean;
     /** App-defined progress detail; collected only when content logging is enabled. */
     readonly payload?: unknown;
-    /** Logger owned by this visit, used to report sub-steps. */
-    readonly subs?: import('../debug.js').SubFlowLogger;
 }
 /** One node of the graph. */
 export type WorkflowNode<State, Result, Runtime = undefined> = {
@@ -94,7 +93,7 @@ export type WorkflowNode<State, Result, Runtime = undefined> = {
     readonly requires?: readonly (keyof State & string)[];
     /** State keys this node is expected to produce; validated after `run`. */
     readonly provides?: readonly (keyof State & string)[];
-    /** Candidate successors, evaluated in order. */
+    /** Candidate successors, evaluated in order. A getter must be pure; registration reads it once. */
     readonly routes: readonly WorkflowRoute<State, Result, Runtime>[];
     /** Return only changed fields. Core commits them after cancellation and output checks. */
     readonly run?: (state: Readonly<State>, context: WorkflowContext<Runtime>) => void | Partial<State> | Promise<void | Partial<State>>;
@@ -103,6 +102,8 @@ export type WorkflowNode<State, Result, Runtime = undefined> = {
 export type AgentWorkflowDefinition<State, Result, Runtime = undefined> = {
     /** Stable workflow id, also reported in every event. */
     readonly id: string;
+    /** App-owned authorized diagnostic reader; no global run storage is installed. */
+    readonly chainSource?: WorkflowChainSource;
     /** Definition revision; lets hosts distinguish executions of different graph versions. */
     readonly revision?: string;
     readonly nodes: readonly WorkflowNode<State, Result, Runtime>[];

package/dist/esm/structs/index.d.ts

@@ -2,9 +2,9 @@
  * Public entry of the structs layer.
  *
  * Structs are the shape-only half of agent-core: declarations and frozen constant catalogs that the
- * runtime modules (`capabilities`, `context`, `execution`, `model`, `kits`, `support`) both
- * implement and consume. Runtime classes declared here only describe shape or initialize fields,
- * so importing this barrel never starts execution.
+ * runtime modules (`tools`, `context`, `execution`, `model`, `kits`, `support`) both implement and
+ * consume. Runtime classes declared here only describe shape or initialize fields, so importing this
+ * barrel never starts execution.
  *
  * Exports: a curated re-export of the shared vocabulary, error classes, diagnostics/event
  * envelopes, model and workflow contracts, and the optional Kit protocol definitions.
@@ -19,6 +19,7 @@ export * from './model/interactions.js';
 export * from './context/journal.js';
 export * from './support/transport/json.js';
 export * from './model/messages.js';
+export * from './model/session.js';
 export * from './model/runtime.js';
 export * from './support/model/provider.js';
 export * from './kits/interaction.js';
@@ -32,10 +33,10 @@ export * from './kits/evidence.js';
 export * from './kits/presentation/templates.js';
 export * from './kits/retrieval.js';
 export * from './kits/text-skills.js';
-export * from './kits/intents/registry.js';
-export * from './kits/intents/scopes.js';
+export * from './kits/domains/registry.js';
+export * from './kits/domains/scopes.js';
 export * from './kits/tools.js';
-export * from './kits/intents/catalog.js';
+export * from './kits/domains/catalog.js';
 export * from './support/registration.js';
 export * from './diagnostics.js';
 export * from './support/context.js';
@@ -55,3 +56,4 @@ export type * from './invocation.js';
 export type * from './debug.js';
 export type * from './execution/events.js';
 export type * from './execution/cache.js';
+export type * from './execution/workflow-views.js';

package/dist/esm/structs/index.js

@@ -2,9 +2,9 @@
  * Public entry of the structs layer.
  *
  * Structs are the shape-only half of agent-core: declarations and frozen constant catalogs that the
- * runtime modules (`capabilities`, `context`, `execution`, `model`, `kits`, `support`) both
- * implement and consume. Runtime classes declared here only describe shape or initialize fields,
- * so importing this barrel never starts execution.
+ * runtime modules (`tools`, `context`, `execution`, `model`, `kits`, `support`) both implement and
+ * consume. Runtime classes declared here only describe shape or initialize fields, so importing this
+ * barrel never starts execution.
  *
  * Exports: a curated re-export of the shared vocabulary, error classes, diagnostics/event
  * envelopes, model and workflow contracts, and the optional Kit protocol definitions.
@@ -19,6 +19,7 @@ export * from './model/interactions.js';
 export * from './context/journal.js';
 export * from './support/transport/json.js';
 export * from './model/messages.js';
+export * from './model/session.js';
 export * from './model/runtime.js';
 export * from './support/model/provider.js';
 export * from './kits/interaction.js';
@@ -32,10 +33,10 @@ export * from './kits/evidence.js';
 export * from './kits/presentation/templates.js';
 export * from './kits/retrieval.js';
 export * from './kits/text-skills.js';
-export * from './kits/intents/registry.js';
-export * from './kits/intents/scopes.js';
+export * from './kits/domains/registry.js';
+export * from './kits/domains/scopes.js';
 export * from './kits/tools.js';
-export * from './kits/intents/catalog.js';
+export * from './kits/domains/catalog.js';
 export * from './support/registration.js';
 export * from './diagnostics.js';
 export * from './support/context.js';

package/dist/esm/structs/kits/answering/tasks.d.ts

@@ -16,8 +16,8 @@ export interface AnswerTaskDefinition<Input = unknown, Data = unknown> {
     readonly readerId: string;
     /** Output contract the answer must satisfy; must be registered. */
     readonly outputId: string;
-    /** Intents this task serves; non-empty. */
-    readonly intentIds: readonly string[];
+    /** Goals this task serves; non-empty. */
+    readonly goalIds: readonly string[];
     /** Optional scope narrowing the task. */
     readonly scopeId?: string;
     /** Checks applied to the produced value; every id must be registered. */

package/dist/esm/structs/kits/{intents → domains}/catalog.d.ts

@@ -1,26 +1,26 @@
 /**
- * Agent catalog contract for the Intents Kit.
+ * Agent catalog contract for the Domain Tools Kit.
  *
  * Place in the package: an optional App-side projection that describes which intents, scopes and
  * tools are available to one request. The ports read the App's real registries, so no parallel
  * capability list exists; this module only declares what the catalog needs from them.
  *
- * Exports: `CatalogIntent`, `CatalogScope`, `CatalogTask`, `CatalogTool`, `DescribedTool`,
+ * Exports: `CatalogGoal`, `CatalogScope`, `CatalogTask`, `CatalogTool`, `DescribedTool`,
  * `AgentCatalogPorts`.
  */
-/** Intent as the catalog sees it: an id plus its declared steps. */
-export interface CatalogIntent<Id extends string = string> {
+/** Goal as the catalog sees it: an id plus its declared delegates. */
+export interface CatalogGoal<Id extends string = string> {
     readonly id: Id;
-    readonly steps: readonly string[];
+    readonly delegates: readonly string[];
 }
 /** Scope as the catalog sees it: an id plus the tools it may use. */
 export interface CatalogScope {
     readonly id: string;
     readonly toolIds: readonly string[];
 }
-/** The task currently accepted for the request, used to narrow the catalog. */
+/** The goal currently accepted for the request, used to narrow the catalog. */
 export interface CatalogTask<Id extends string = string> {
-    readonly intentId: Id;
+    readonly goalId: Id;
     /** Selected scope; `null` or `undefined` means a scope has not been chosen yet. */
     readonly scopeId?: string | null;
 }
@@ -28,12 +28,12 @@ export interface CatalogTask<Id extends string = string> {
 export interface CatalogTool<App> {
     readonly id: string;
     /** Intent ids the tool serves, or `'all'` when it is always available. */
-    readonly intentIds: 'all' | readonly string[];
+    readonly goalIds: 'all' | readonly string[];
     /** Returns whether the tool may run for this App state; absent means always available. */
-    available?(app: App): boolean;
-    /** Invocation step, when the tool participates in the step-based lifecycle. */
-    readonly invocation?: {
-        readonly step: string;
+    readonly active?: import('../../capabilities/model.js').ToolCondition<App>;
+    /** Invocation identity, when the tool participates in the lifecycle. */
+    readonly lifecycle?: {
+        readonly id?: string;
     };
 }
 /** Model- or host-facing description of one tool. */
@@ -43,15 +43,15 @@ export interface DescribedTool {
     readonly description: string;
     readonly audience: string;
     readonly effect: string;
-    readonly intentIds: readonly string[];
+    readonly goalIds: readonly string[];
 }
 /** Ports the catalog reads from the App's registries. */
-export interface AgentCatalogPorts<App, Id extends string, Intent extends CatalogIntent<Id>, Scope extends CatalogScope> {
-    /** All registered intent ids, before availability filtering. */
-    intentIds(): readonly Id[];
-    /** Registered intents, optionally narrowed to `ids`. */
-    intents(ids?: readonly Id[]): readonly Intent[];
-    /** Registered scopes for the given intent ids (all scopes when omitted). */
+export interface AgentCatalogPorts<App, Id extends string, Intent extends CatalogGoal<Id>, Scope extends CatalogScope> {
+    /** All registered Tool ids, before availability filtering. */
+    goalIds(app: App): readonly Id[];
+    /** Registered domain Tools, optionally narrowed to `ids`. */
+    goals(ids?: readonly Id[]): readonly Intent[];
+    /** Registered scopes for the given Tool ids (all scopes when omitted). */
     scopes(ids?: readonly Id[]): readonly Scope[];
     /** When not `false`, the catalog is narrowed to `currentTask`; defaults to restriction on. */
     readonly restrictToTask?: boolean;
@@ -60,7 +60,7 @@ export interface AgentCatalogPorts<App, Id extends string, Intent extends Catalo
     readonly tools: {
         values(): Iterable<CatalogTool<App>>;
         has(id: string): boolean;
-        supportsIntent(id: Id, app: App): boolean;
+        supportsGoal(id: Id, app: App): boolean;
         /** Describes tools for an audience (for example `'model'`); must be synchronous. */
         describe(audience?: string, app?: App): readonly DescribedTool[];
     };