@primo-ai/sdk 0.1.3 → 0.1.5

package/README.md

@@ -12,8 +12,9 @@ This package contains all shared types used across the AgentForge monorepo. It h
 
 | Type | Description |
 |------|-------------|
-| `PipelineStage` | Union of all 13 stage names |
-| `StageName` | `PipelineStage` plus arbitrary plugin-defined strings |
+| `PipelineStage` | Union of 10 main agent lifecycle stages |
+| `ToolExecutionStage` | Sub-pipeline stages: `beforeTool`, `execute`, `afterTool` |
+| `StageName` | `PipelineStage \| ToolExecutionStage` plus arbitrary plugin-defined strings |
 | `Processor` | `{ stage, execute(context) => Promise<ProcessorResult> }` |
 | `ProcessorResult` | `PipelineContext \| AbortSignal \| SuspensionSignal` |
 | `PipelineContext` | Container with `request`, `agent`, `iteration`, `session` regions |

package/dist/index.d.ts

@@ -1,7 +1,9 @@
-/** The agent lifecycle stages + gate stages + tool sub-pipeline stages. */
-export type PipelineStage = 'processInput' | 'buildContext' | 'prepareStep' | 'gateLLM' | 'invokeLLM' | 'processStepOutput' | 'gateTool' | 'executeTools' | 'evaluateIteration' | 'processOutput' | 'beforeTool' | 'execute' | 'afterTool';
+/** Agent lifecycle stages: pre-loop setup, agentic loop, and post-loop output. */
+export type PipelineStage = 'processInput' | 'buildContext' | 'prepareStep' | 'gateLLM' | 'invokeLLM' | 'processStepOutput' | 'gateTool' | 'executeTools' | 'evaluateIteration' | 'processOutput';
+/** Tool execution sub-pipeline stages — internal to ToolRegistry. */
+export type ToolExecutionStage = 'beforeTool' | 'execute' | 'afterTool';
 /** Stage name that accepts built-in stages AND arbitrary plugin-defined strings. */
-export type StageName = PipelineStage | (string & {});
+export type StageName = PipelineStage | ToolExecutionStage | (string & {});
 /** A mutation operation applied to a pipeline phase's stage list. */
 export type StageMutation = {
     type: 'insert';
@@ -106,11 +108,11 @@ export interface IterationRegion {
     loopDirective?: LoopDirective;
     /** AI SDK fullStream yielding text-delta, tool-call, finish-step, error events. */
     fullStream?: AsyncIterable<unknown>;
-    usagePromise?: Promise<TokenUsage>;
+    usagePromise?: Promise<TokenUsage | null>;
     /** Promise resolving to reasoning text from the model (e.g. DeepSeek reasoning_content). */
     reasoningPromise?: Promise<string | undefined>;
     response?: string;
-    tokenUsage?: TokenUsage;
+    tokenUsage?: TokenUsage | null;
     /** Tool calls extracted from the LLM response by PipelineRunner stream consumption. */
     pendingToolCalls?: ToolCall[];
     /** Reasoning content from thinking-mode models (e.g. DeepSeek). Must be passed back on subsequent turns. */
@@ -124,7 +126,10 @@ export interface IterationRegion {
 export interface SessionRegion {
     messageHistory?: Message[];
     totalTokenUsage?: TokenUsage;
-    /** Plugin extension point. Namespaced by plugin ID. */
+    /**
+     * Plugin extension point. Use plugin ID as key name to avoid collisions.
+     * Type-safe usage: SimpleProcessorContext.getState<MyPluginState>('myPlugin')
+     */
     custom: Record<string, unknown>;
 }
 export interface PipelineContext {
@@ -156,7 +161,25 @@ export interface SuspensionSignal {
     checkpoint: PipelineCheckpoint;
     expiresAt?: string;
 }
-export type ProcessorResult = PipelineContext | AbortSignal | SuspensionSignal;
+export interface ErrorResult {
+    type: 'error';
+    error: Error;
+    stage: StageName;
+    recoverable?: boolean;
+}
+export type ProcessorResult = PipelineContext | AbortSignal | SuspensionSignal | ErrorResult;
+/**
+ * Processor -- Business logic unit in the pipeline. CAN read and modify PipelineContext.
+ * Use for: context assembly, LLM calls, tool execution, iteration evaluation.
+ *
+ * Hook -- Observation/interception point in the pipeline. CANNOT modify Context.
+ * Use for: logging, metrics, event emission, permission checks (allow/deny).
+ *
+ * Boundary rules:
+ * - Need to modify ctx -> Use Processor
+ * - Need to intercept/deny -> Use Hook
+ * - Only need to observe -> Use Event (subscribe/on)
+ */
 export interface Processor {
     stage: StageName;
     execute(context: PipelineContext): Promise<ProcessorResult>;
@@ -282,7 +305,36 @@ export type StreamEvent = {
     suspensionId: string;
     reason: string;
     checkpoint: PipelineCheckpoint;
+} | {
+    type: 'error';
+    error: Error;
+    stage: StageName;
+    recoverable?: boolean;
+} | {
+    type: 'session.started';
+    sessionId: string;
+} | {
+    type: 'session.completed';
+    sessionId: string;
+    tokenUsage: TokenUsage;
+} | {
+    type: 'session.aborted';
+    sessionId: string;
+} | {
+    type: 'permission.request';
+    sessionId: string;
+    permissionId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+    reason: string;
+} | {
+    type: 'permission.resolved';
+    sessionId: string;
+    permissionId: string;
+    decision: 'allow' | 'deny';
 };
+/** @deprecated Use StreamEvent — the union now includes all event types */
+export type ServerStreamEvent = StreamEvent;
 export type EventType = 'agent:start' | 'agent:end' | 'tool:before' | 'tool:after' | string;
 export type HookPoint = 'agent.start' | 'agent.end' | 'stage.before' | 'stage.after' | 'llm.before' | 'llm.after' | 'tool.before' | 'tool.after' | 'iteration.end' | 'error';
 export type HookProfile = 'minimal' | 'standard' | 'strict';
@@ -324,21 +376,38 @@ export interface ResourceDeclaration {
     start: () => Promise<unknown>;
     stop: (instance: unknown) => Promise<void>;
 }
-export interface HarnessAPI {
+/** Pipeline extension: register Processors */
+export interface PipelineRegistry {
     registerProcessor(stage: StageName, processor: Processor): void;
+}
+/** Tool registration */
+export interface ToolRegistryAPI {
     registerTool(tool: ToolDefinition): void;
     unregisterTool(name: string): boolean;
-    registerCommand(name: string, handler: (args: string) => Promise<void>): void;
+}
+/** Interception & events */
+export interface InterceptionAPI {
     registerHook(hook: Hook): void;
     subscribe(eventType: string, handler: (data?: unknown) => void): () => void;
-    registerResource(declaration: ResourceDeclaration): void;
-    registerProvider(name: string, factory: unknown): void;
-    registerCompressionStrategy(strategy: CompressionStrategy): void;
     emit(eventType: string, data?: unknown): void;
+}
+/** Pipeline stage mutation (frozen after agent starts) */
+export interface StageMutationAPI {
     insertStage(phase: 'preLoop' | 'loop' | 'postLoop', after: StageName, newStage: StageName): void;
     removeStage(phase: 'preLoop' | 'loop' | 'postLoop', stage: StageName): void;
     replaceStages(phase: 'preLoop' | 'loop' | 'postLoop', stages: StageName[]): void;
 }
+/** Lifecycle & model providers */
+export interface LifecycleAPI {
+    registerResource(declaration: ResourceDeclaration): void;
+    registerProvider(name: string, factory: unknown): void;
+    registerCompressionStrategy(strategy: CompressionStrategy): void;
+    registerCommand(name: string, handler: (args: string) => Promise<void>): void;
+}
+/** Full Harness API — composes all sub-interfaces.
+ *  Plugin devs can depend on individual sub-interfaces for selective dependency. */
+export interface HarnessAPI extends PipelineRegistry, ToolRegistryAPI, InterceptionAPI, StageMutationAPI, LifecycleAPI {
+}
 export interface PluginRegistration {
     processors?: Processor[];
     tools?: ToolDefinition[];
@@ -373,6 +442,13 @@ export interface AgentConfig {
      */
     requiredToolPolicy?: 'advise' | 'enforce';
 }
+/** Convenience config for single-agent usage. Static fields only — no Dynamic<T> or advanced options. */
+export interface AgentSimpleConfig {
+    model: string;
+    systemPrompt?: string;
+    maxIterations?: number;
+    tools?: Tool[];
+}
 /** Context passed to Dynamic<T> resolver functions at processInput stage. */
 export interface ResolveContext {
     input: string;
@@ -438,6 +514,7 @@ export interface GatewayConfig {
 }
 /**
  * Top-level framework configuration.
+ * @internal For multi-agent and server deployments. For single-agent usage, use `AgentSimpleConfig` or `createAgent()`.
  * Merged from multiple layers (highest priority first):
  *   1. Session-level — runtime parameters passed to agent.run()
  *   2. Project-level — .agentforge/config.jsonc in project root
@@ -483,7 +560,7 @@ export interface HarnessConfig {
         facts: string[] | ((ctx: PipelineContext) => string[] | Promise<string[]>);
     };
 }
-export type SessionStatus = 'active' | 'completed' | 'suspended' | 'error';
+export type SessionStatus = 'active' | 'completed' | 'suspended' | 'cancelled' | 'error';
 export interface SessionRecord {
     sessionId: string;
     parentSessionId?: string;
@@ -507,6 +584,12 @@ export interface SessionStorage {
         status?: SessionStatus;
     }): Promise<SessionRecord[]>;
     updateMeta(sessionId: string, meta: Partial<SessionRecord>): Promise<void>;
+    get(sessionId: string): Promise<SessionRecord | undefined>;
+    delete(sessionId: string): Promise<void>;
+    getMessages(sessionId: string, options?: {
+        limit?: number;
+        before?: string;
+    }): Promise<Message[]>;
 }
 export interface CheckpointStore<T = unknown> {
     save(sessionId: string, data: T): Promise<void>;
@@ -621,3 +704,4 @@ export interface AgentProfile {
     model?: string;
     maxIterations?: number;
 }
+export { SimpleProcessorContext } from './simple-context.js';

package/dist/index.js

@@ -62,3 +62,7 @@ export const SpanAttributeKeys = {
 // ---------------------------------------------------------------------------
 export { AgentForgeClient } from './client.js';
 export { parseSSE } from './client.js';
+// ---------------------------------------------------------------------------
+// SimpleProcessorContext -- flat PipelineContext convenience wrapper
+// ---------------------------------------------------------------------------
+export { SimpleProcessorContext } from './simple-context.js';

package/dist/simple-context.d.ts

@@ -0,0 +1,23 @@
+import type { PipelineContext, AgentConfig, LoopDirective, Message, TokenUsage } from './index.js';
+/**
+ * Flat wrapper for PipelineContext.
+ * Provides direct access to common fields without deep nesting.
+ * Wraps by reference -- no data copying.
+ */
+export declare class SimpleProcessorContext {
+    private ctx;
+    constructor(ctx: PipelineContext);
+    get input(): string;
+    get sessionId(): string;
+    get model(): string;
+    get systemPrompt(): string | undefined;
+    getConfig<T = AgentConfig>(): T;
+    get step(): number;
+    get response(): string | undefined;
+    get loopDirective(): LoopDirective | undefined;
+    get messages(): Message[];
+    get totalTokens(): TokenUsage | undefined;
+    getState<T = unknown>(namespace: string): T | undefined;
+    setState(namespace: string, value: unknown): void;
+    get raw(): PipelineContext;
+}

package/dist/simple-context.js

@@ -0,0 +1,34 @@
+/**
+ * Flat wrapper for PipelineContext.
+ * Provides direct access to common fields without deep nesting.
+ * Wraps by reference -- no data copying.
+ */
+export class SimpleProcessorContext {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    // Request region (immutable)
+    get input() { return this.ctx.request.input; }
+    get sessionId() { return this.ctx.request.sessionId; }
+    // Agent region
+    get model() { return this.ctx.agent.config.model; }
+    get systemPrompt() { return this.ctx.agent.systemPrompt; }
+    getConfig() { return this.ctx.agent.config; }
+    // Iteration region
+    get step() { return this.ctx.iteration.step; }
+    get response() { return this.ctx.iteration.response; }
+    get loopDirective() { return this.ctx.iteration.loopDirective; }
+    // Session region
+    get messages() { return this.ctx.session.messageHistory ?? []; }
+    get totalTokens() { return this.ctx.session.totalTokenUsage; }
+    // Plugin namespace data (type-safe access)
+    getState(namespace) {
+        return this.ctx.session.custom[namespace];
+    }
+    setState(namespace, value) {
+        this.ctx.session.custom[namespace] = value;
+    }
+    // Raw Context access (escape hatch for advanced use)
+    get raw() { return this.ctx; }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primo-ai/sdk",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",