@lssm/lib.ai-agent 0.0.0-canary-20251206160926

package/dist/tools/tool-adapter.d.ts

@@ -0,0 +1,49 @@
+import { AgentToolConfig } from "../spec/spec.js";
+import { ToolExecutionContext, ToolHandler } from "../types.js";
+import { Tool } from "ai";
+
+//#region src/tools/tool-adapter.d.ts
+
+/**
+ * Convert ContractSpec AgentToolConfig to AI SDK CoreTool.
+ *
+ * @param specTool - The tool configuration from AgentSpec
+ * @param handler - The handler function for the tool
+ * @param context - Partial context to inject into handler calls
+ * @returns AI SDK CoreTool
+ */
+declare function specToolToAISDKTool(specTool: AgentToolConfig, handler: ToolHandler, context?: Partial<ToolExecutionContext>): Tool<any, any>;
+/**
+ * Convert multiple ContractSpec tool configs to AI SDK tools.
+ *
+ * @param specTools - Array of tool configurations
+ * @param handlers - Map of tool name to handler function
+ * @param context - Partial context to inject into handler calls
+ * @returns Record of AI SDK tools keyed by name
+ */
+declare function specToolsToAISDKTools(specTools: AgentToolConfig[], handlers: Map<string, ToolHandler>, context?: Partial<ToolExecutionContext>): Record<string, Tool<any, any>>;
+/**
+ * Type-safe tool handler builder.
+ *
+ * @example
+ * ```typescript
+ * const handler = createToolHandler<{ query: string }>((input, ctx) => {
+ *   return `Searched for: ${input.query}`;
+ * });
+ * ```
+ */
+declare function createToolHandler<TInput = unknown, TOutput = string>(handler: (input: TInput, context: ToolExecutionContext) => Promise<TOutput> | TOutput): ToolHandler<TInput, TOutput>;
+/**
+ * Build a tool handlers map from an object.
+ *
+ * @example
+ * ```typescript
+ * const handlers = buildToolHandlers({
+ *   search: async (input: { query: string }) => `Found: ${input.query}`,
+ *   calculate: async (input: { a: number, b: number }) => `${input.a + input.b}`,
+ * });
+ * ```
+ */
+declare function buildToolHandlers(handlersObj: Record<string, ToolHandler>): Map<string, ToolHandler>;
+//#endregion
+export { buildToolHandlers, createToolHandler, specToolToAISDKTool, specToolsToAISDKTools };

package/dist/tools/tool-adapter.js

@@ -0,0 +1 @@
+import{jsonSchemaToZodSafe as e}from"../schema/json-schema-to-zod.js";import{tool as t}from"ai";function n(n,r,i={}){return t({description:n.description??n.name,inputSchema:e(n.schema),needsApproval:n.requiresApproval??!n.automationSafe,execute:async e=>{let t=await r(e,{agentId:i.agentId??`unknown`,sessionId:i.sessionId??`unknown`,tenantId:i.tenantId,actorId:i.actorId,metadata:i.metadata,signal:i.signal});return typeof t==`string`?t:JSON.stringify(t)}})}function r(e,t,r={}){let i={};for(let a of e){let e=t.get(a.name);if(!e)throw Error(`Missing handler for tool: ${a.name}`);i[a.name]=n(a,e,r)}return i}function i(e){return async(t,n)=>e(t,n)}function a(e){return new Map(Object.entries(e))}export{a as buildToolHandlers,i as createToolHandler,n as specToolToAISDKTool,r as specToolsToAISDKTools};

package/dist/types.d.ts

@@ -0,0 +1,194 @@
+import { LanguageModelUsage, ModelMessage, StepResult, ToolSet } from "ai";
+
+//#region src/types.d.ts
+
+/**
+ * Simplified tool call type for ContractSpec usage.
+ * Compatible with AI SDK v6 TypedToolCall.
+ */
+interface ToolCallInfo {
+  type: 'tool-call';
+  toolCallId: string;
+  toolName: string;
+  args: unknown;
+}
+/**
+ * Simplified tool result type for ContractSpec usage.
+ * Compatible with AI SDK v6 TypedToolResult.
+ */
+interface ToolResultInfo {
+  type: 'tool-result';
+  toolCallId: string;
+  toolName: string;
+  output: unknown;
+}
+/**
+ * Extended message type that adds metadata support to ModelMessage.
+ * Used for session memory tracking.
+ */
+interface AgentMessage {
+  role: 'user' | 'assistant' | 'system' | 'tool';
+  content: string | {
+    type: string;
+    text?: string;
+    [key: string]: unknown;
+  }[];
+  metadata?: Record<string, string>;
+}
+type AgentStatus = 'idle' | 'running' | 'waiting' | 'completed' | 'failed' | 'escalated';
+type AgentEventName = 'agent.session.created' | 'agent.session.updated' | 'agent.step.started' | 'agent.step.completed' | 'agent.tool.called' | 'agent.tool.completed' | 'agent.tool.failed' | 'agent.tool.approval_requested' | 'agent.escalated' | 'agent.completed' | 'agent.failed';
+interface AgentEventPayload {
+  sessionId: string;
+  agentId: string;
+  tenantId?: string;
+  stepIndex?: number;
+  toolName?: string;
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Runtime context passed to agent calls via AI SDK v6 callOptionsSchema.
+ * Maps to ContractSpec's tenant/actor system.
+ */
+interface AgentCallOptions {
+  /** Tenant scoping for guardrails and data isolation */
+  tenantId?: string;
+  /** Unique end-user identifier (for personalization) */
+  actorId?: string;
+  /** Session to resume; new session created when omitted */
+  sessionId?: string;
+  /** Arbitrary metadata forwarded to events and tool handlers */
+  metadata?: Record<string, string>;
+}
+interface AgentSessionState {
+  sessionId: string;
+  agentId: string;
+  tenantId?: string;
+  actorId?: string;
+  status: AgentStatus;
+  messages: ModelMessage[];
+  steps: StepResult<ToolSet>[];
+  createdAt: Date;
+  updatedAt: Date;
+  metadata?: Record<string, string>;
+}
+interface AgentGenerateParams {
+  /** User prompt or message */
+  prompt: string;
+  /** System prompt override (appended to agent instructions) */
+  systemOverride?: string;
+  /** Runtime context options */
+  options?: AgentCallOptions;
+  /** Maximum number of steps/iterations */
+  maxSteps?: number;
+  /** Abort signal for cancellation */
+  signal?: AbortSignal;
+}
+interface AgentStreamParams extends AgentGenerateParams {
+  /** Called when a step completes */
+  onStepFinish?: (step: StepResult<ToolSet>) => void | Promise<void>;
+}
+interface AgentGenerateResult<TOutput = string> {
+  /** The final text response */
+  text: string;
+  /** Structured output if configured */
+  output?: TOutput;
+  /** All steps taken during generation */
+  steps: StepResult<ToolSet>[];
+  /** All tool calls made during generation */
+  toolCalls: ToolCallInfo[];
+  /** All tool results */
+  toolResults: ToolResultInfo[];
+  /** Reason generation finished */
+  finishReason: 'stop' | 'tool-calls' | 'length' | 'content-filter' | 'error' | 'other' | 'unknown';
+  /** Token usage statistics */
+  usage?: LanguageModelUsage;
+  /** Updated session state */
+  session?: AgentSessionState;
+  /** Whether approval is pending for a tool call */
+  pendingApproval?: {
+    toolName: string;
+    toolCallId: string;
+    args: unknown;
+  };
+}
+/**
+ * Context provided to tool handlers during execution.
+ */
+interface ToolExecutionContext {
+  agentId: string;
+  sessionId: string;
+  tenantId?: string;
+  actorId?: string;
+  metadata?: Record<string, string>;
+  signal?: AbortSignal;
+}
+/**
+ * Handler function for a tool.
+ */
+type ToolHandler<TInput = unknown, TOutput = string> = (input: TInput, context: ToolExecutionContext) => Promise<TOutput>;
+interface AgentStepMetrics {
+  agentId: string;
+  stepIndex: number;
+  toolCalls: {
+    toolName: string;
+    durationMs?: number;
+    success: boolean;
+    error?: string;
+  }[];
+  finishReason: string;
+  usage?: LanguageModelUsage;
+  timestamp: Date;
+}
+type AgentEventEmitter = (event: AgentEventName, payload: AgentEventPayload) => void | Promise<void>;
+/** @deprecated Use AgentGenerateParams instead */
+interface AgentRunRequestInput {
+  agent: string;
+  version?: number;
+  input: string;
+  tenantId?: string;
+  actorId?: string;
+  sessionId?: string;
+  metadata?: Record<string, string>;
+  instructionsOverride?: string;
+}
+/** @deprecated Use AgentGenerateResult instead */
+interface AgentRunResult {
+  session: AgentSessionState;
+  outputText: string;
+  confidence: number;
+  iterations: number;
+  requiresEscalation: boolean;
+  approvalRequestId?: string;
+  finishReason: string;
+  toolInvocations: AgentToolInvocation[];
+}
+/** @deprecated Use ToolCallInfo instead */
+interface AgentToolInvocation {
+  name: string;
+  arguments: unknown;
+  startedAt: Date;
+  completedAt?: Date;
+  durationMs?: number;
+  success: boolean;
+  error?: string;
+}
+/** @deprecated Use ToolExecutionContext instead */
+interface AgentToolContext {
+  session: AgentSessionState;
+  tenantId?: string;
+  actorId?: string;
+  metadata?: Record<string, string>;
+  emit: (event: AgentEventName, payload: AgentEventPayload) => void;
+}
+/** @deprecated Use ToolHandler instead */
+interface AgentToolResult {
+  content: string;
+  citations?: {
+    label: string;
+    url?: string;
+    snippet?: string;
+  }[];
+  metadata?: Record<string, string>;
+}
+//#endregion
+export { AgentCallOptions, AgentEventEmitter, AgentEventName, AgentEventPayload, AgentGenerateParams, AgentGenerateResult, AgentMessage, AgentRunRequestInput, AgentRunResult, AgentSessionState, AgentStatus, AgentStepMetrics, AgentStreamParams, AgentToolContext, AgentToolInvocation, AgentToolResult, ToolCallInfo, ToolExecutionContext, ToolHandler, ToolResultInfo };

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@lssm/lib.ai-agent",
+  "version": "0.0.0-canary-20251206160926",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "build": "bun build:bundle && bun build:types",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "ai": "beta",
+    "@ai-sdk/mcp": "beta",
+    "@ai-sdk/mistral": "beta",
+    "@ai-sdk/openai": "beta",
+    "@ai-sdk/anthropic": "beta",
+    "@modelcontextprotocol/sdk": "^1.24.3",
+    "@lssm/lib.contracts": "workspace:*",
+    "@lssm/lib.knowledge": "workspace:*",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@lssm/tool.tsdown": "workspace:*",
+    "@lssm/tool.typescript": "workspace:*",
+    "tsdown": "^0.17.0",
+    "typescript": "^5.9.3"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./agent": "./dist/agent/index.js",
+    "./agent/agent-factory": "./dist/agent/agent-factory.js",
+    "./agent/contract-spec-agent": "./dist/agent/contract-spec-agent.js",
+    "./approval": "./dist/approval/index.js",
+    "./approval/workflow": "./dist/approval/workflow.js",
+    "./knowledge": "./dist/knowledge/index.js",
+    "./knowledge/injector": "./dist/knowledge/injector.js",
+    "./memory": "./dist/memory/index.js",
+    "./memory/in-memory": "./dist/memory/in-memory.js",
+    "./memory/manager": "./dist/memory/manager.js",
+    "./schema": "./dist/schema/index.js",
+    "./schema/json-schema-to-zod": "./dist/schema/json-schema-to-zod.js",
+    "./schema/schema-output": "./dist/schema/schema-output.js",
+    "./session": "./dist/session/index.js",
+    "./session/store": "./dist/session/store.js",
+    "./spec": "./dist/spec/index.js",
+    "./spec/registry": "./dist/spec/registry.js",
+    "./spec/spec": "./dist/spec/spec.js",
+    "./telemetry": "./dist/telemetry/index.js",
+    "./telemetry/adapter": "./dist/telemetry/adapter.js",
+    "./tools": "./dist/tools/index.js",
+    "./tools/knowledge-tool": "./dist/tools/knowledge-tool.js",
+    "./tools/mcp-client": "./dist/tools/mcp-client.js",
+    "./tools/mcp-server": "./dist/tools/mcp-server.js",
+    "./tools/tool-adapter": "./dist/tools/tool-adapter.js",
+    "./types": "./dist/types.js",
+    "./*": "./*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}