@agntk/core 0.3.0 → 0.3.1

package/dist/agent-v2.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @agntk/core - V2 Agent Factory
+ *
+ * A fully-equipped agent that shows up ready. No roles, no tool presets,
+ * no feature flags. You give it a name, tell it what it's doing, and
+ * point it at a task. It figures out the rest.
+ *
+ * Every capability is auto-detected from the environment:
+ * - Tools: ALL tools, always
+ * - Memory: always on, stored at ~/.agntk/agents/{name}/
+ * - Durability: auto-detected (workflow package installed → on)
+ * - Telemetry: auto-detected (LANGFUSE_PUBLIC_KEY set → on)
+ * - Skills: auto-discovered from standard directories
+ * - Sub-agents: always enabled with team coordination
+ * - Reflection: always on (reflact strategy)
+ * - Approval: always on for dangerous tools
+ * - Model: auto-selected from available API keys
+ */
+import type { AgentOptionsV2, AgentV2 } from './types/agent-v2.js';
+/**
+ * Create a v2 agent — fully equipped, zero config.
+ *
+ * @example
+ * ```typescript
+ * const agent = createAgentV2({
+ *   name: 'deploy-bot',
+ *   instructions: 'You manage deployments for our k8s cluster.',
+ * });
+ *
+ * const result = await agent.stream({ prompt: 'Roll back staging to yesterday' });
+ * for await (const chunk of result.fullStream) {
+ *   if (chunk.type === 'text-delta') process.stdout.write(chunk.text ?? '');
+ * }
+ * ```
+ */
+/**
+ * Internal options not exposed in the public API.
+ * Used by the factory when recursively creating sub-agents.
+ */
+interface InternalV2Options {
+    /** Current spawn depth. 0 = top-level agent. */
+    _spawnDepth?: number;
+    /** Parent agent name, for naming sub-agents. */
+    _parentName?: string;
+}
+export declare function createAgentV2(options: AgentOptionsV2, _internal?: InternalV2Options): AgentV2;
+export default createAgentV2;
+//# sourceMappingURL=agent-v2.d.ts.map

package/dist/agent-v2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-v2.d.ts","sourceRoot":"","sources":["../src/agent-v2.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAOH,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAuB,MAAM,kBAAkB,CAAC;AAuGrF;;;;;;;;;;;;;;;GAeG;AACH;;;GAGG;AACH,UAAU,iBAAiB;IACzB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,EAAE,SAAS,GAAE,iBAAsB,GAAG,OAAO,CAkTjG;AAED,eAAe,aAAa,CAAC"}

package/dist/agent-v2.js

@@ -0,0 +1,365 @@
+/**
+ * @agntk/core - V2 Agent Factory
+ *
+ * A fully-equipped agent that shows up ready. No roles, no tool presets,
+ * no feature flags. You give it a name, tell it what it's doing, and
+ * point it at a task. It figures out the rest.
+ *
+ * Every capability is auto-detected from the environment:
+ * - Tools: ALL tools, always
+ * - Memory: always on, stored at ~/.agntk/agents/{name}/
+ * - Durability: auto-detected (workflow package installed → on)
+ * - Telemetry: auto-detected (LANGFUSE_PUBLIC_KEY set → on)
+ * - Skills: auto-discovered from standard directories
+ * - Sub-agents: always enabled with team coordination
+ * - Reflection: always on (reflact strategy)
+ * - Approval: always on for dangerous tools
+ * - Model: auto-selected from available API keys
+ */
+import { resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { ToolLoopAgent, stepCountIs } from 'ai';
+import { createLogger } from '@agntk/logger';
+import { usageLimitStop } from './usage-limits.js';
+import { resolveModel } from './models.js';
+import { createToolPreset } from './presets/tools.js';
+import { createSpawnAgentTool } from './tools/spawn-agent/index.js';
+import { wrapAllToolsWithRetry } from './tools/model-retry.js';
+import { discoverSkills, filterEligibleSkills, buildSkillsSystemPrompt, loadSkillContent } from './skills/index.js';
+import { checkWorkflowAvailability } from './workflow/utils.js';
+import { wrapToolsAsDurable } from './workflow/durable-tool.js';
+import { createReflectionPrepareStep } from './reflection.js';
+// import { applyApproval } from './tools/approval.js'; // Disabled until approval handler is wired up
+import { runGuardrails, handleGuardrailResults } from './guardrails/runner.js';
+import { contentFilter } from './guardrails/built-ins.js';
+import { MarkdownMemoryStore } from './memory/store.js';
+import { loadMemoryContext } from './memory/loader.js';
+import { createMemoryTools } from './memory/tools.js';
+import { initObservability, createTelemetrySettings } from './observability/index.js';
+import { buildDynamicSystemPrompt } from './prompts/context.js';
+// ============================================================================
+// Logger
+// ============================================================================
+const log = createLogger('@agntk/core:agent-v2');
+// ============================================================================
+// Constants
+// ============================================================================
+const DEFAULT_MAX_STEPS = 25;
+const SUB_AGENT_MAX_STEPS = 15;
+const DEFAULT_MAX_SPAWN_DEPTH = 2;
+const AGENT_STATE_BASE = '.agntk/agents';
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Resolve the persistent state directory for a named agent.
+ * ~/.agntk/agents/{name}/
+ */
+function resolveAgentStatePath(name) {
+    // Sanitize name for filesystem
+    const safeName = name.replace(/[^a-zA-Z0-9_-]/g, '_').toLowerCase();
+    return resolve(homedir(), AGENT_STATE_BASE, safeName);
+}
+/**
+ * Detect if telemetry should be enabled from env vars.
+ */
+function detectTelemetry() {
+    return !!(process.env.LANGFUSE_PUBLIC_KEY &&
+        process.env.LANGFUSE_SECRET_KEY);
+}
+/**
+ * Build the base instructions for the agent.
+ * Combines user instructions with auto-discovered skills.
+ */
+function buildBaseInstructions(name, userInstructions, skillsPrompt) {
+    const parts = [];
+    // Core identity
+    parts.push(`You are ${name}, a capable AI agent.`);
+    // User instructions
+    if (userInstructions) {
+        parts.push('');
+        parts.push(userInstructions);
+    }
+    // Agent capabilities reminder
+    parts.push('');
+    parts.push('You have access to a full suite of tools including file operations, ' +
+        'shell commands, code search (grep, glob, ast-grep), a browser, ' +
+        'deep reasoning, planning, and persistent memory. ' +
+        'You can spawn sub-agents for complex tasks that benefit from delegation. ' +
+        'Use the remember tool to persist important findings across sessions. ' +
+        'Use the recall tool to search your memory for relevant context.');
+    // Skills
+    if (skillsPrompt) {
+        parts.push('');
+        parts.push(skillsPrompt);
+    }
+    return parts.join('\n');
+}
+export function createAgentV2(options, _internal = {}) {
+    const { name, instructions, workspaceRoot = process.cwd(), } = options;
+    const spawnDepth = _internal._spawnDepth ?? 0;
+    const isSubAgent = spawnDepth > 0;
+    const maxSteps = options.maxSteps ?? (isSubAgent ? SUB_AGENT_MAX_STEPS : DEFAULT_MAX_STEPS);
+    log.info('Creating v2 agent', { name, maxSteps, workspaceRoot, spawnDepth });
+    // ── 1. Resolve model ──────────────────────────────────────────────────
+    // User override takes priority, otherwise auto-select from available API keys.
+    const model = options.model ?? resolveModel({ tier: 'standard' });
+    log.debug('Model resolved', { hasExplicitModel: !!options.model });
+    // ── 2. Build ALL tools (no presets, no filtering) ─────────────────────
+    // The 'full' preset creates every tool we have.
+    let tools = createToolPreset('full', { workspaceRoot });
+    log.debug('Base tools built', { count: Object.keys(tools).length, tools: Object.keys(tools) });
+    // ── 3. Memory — always on ─────────────────────────────────────────────
+    // Each named agent gets persistent state at ~/.agntk/agents/{name}/
+    const agentStatePath = resolveAgentStatePath(name);
+    const memoryStore = new MarkdownMemoryStore({
+        projectDir: agentStatePath,
+        globalDir: '.agntk', // Global identity/preferences at ~/.agntk/
+        workspaceRoot,
+    });
+    const memoryTools = createMemoryTools({ store: memoryStore, model });
+    Object.assign(tools, memoryTools);
+    log.info('Memory enabled', {
+        agentStatePath,
+        projectPath: memoryStore.getProjectPath(),
+        globalPath: memoryStore.getGlobalPath(),
+        tools: Object.keys(memoryTools),
+    });
+    // ── 4. Sub-agents — recursive v2 creation ──────────────────────────────
+    // Sub-agents are full v2 agents. At max depth, spawn tool is omitted.
+    if (spawnDepth < DEFAULT_MAX_SPAWN_DEPTH) {
+        const spawnTool = createSpawnAgentTool({
+            maxSpawnDepth: DEFAULT_MAX_SPAWN_DEPTH,
+            currentDepth: spawnDepth,
+            createAgent: (subAgentOptions) => {
+                const subName = `${name}/${subAgentOptions.role}`;
+                log.info('Spawning sub-agent', { parentName: name, subName, role: subAgentOptions.role });
+                // Create a full v2 sub-agent with depth+1.
+                // It gets all tools, its own memory under the parent's state dir,
+                // and won't get a spawn tool if at max depth.
+                const subAgent = createAgentV2({
+                    name: subName,
+                    instructions: subAgentOptions.instructions,
+                    workspaceRoot,
+                    maxSteps: SUB_AGENT_MAX_STEPS,
+                    model: options.model, // Inherit parent's model
+                }, {
+                    _spawnDepth: spawnDepth + 1,
+                    _parentName: name,
+                });
+                return {
+                    stream: (input) => {
+                        const streamPromise = subAgent.stream(input);
+                        return {
+                            fullStream: (async function* () {
+                                const result = await streamPromise;
+                                for await (const chunk of result.fullStream) {
+                                    yield chunk;
+                                }
+                            })(),
+                            text: streamPromise.then((r) => r.text),
+                        };
+                    },
+                };
+            },
+        });
+        tools = { ...tools, spawn_agent: spawnTool };
+        log.debug('Sub-agents enabled', { maxSpawnDepth: DEFAULT_MAX_SPAWN_DEPTH, currentDepth: spawnDepth });
+    }
+    else {
+        log.debug('Sub-agents disabled (at max spawn depth)', { spawnDepth });
+    }
+    // ── 5. Approval — off by default ─────────────────────────────────────
+    // The v2 agent is run by a person who trusts it. Approval can be
+    // re-enabled when we add a proper approval handler to the CLI/SDK.
+    // Without a handler, needsApproval: true silently blocks tool execution.
+    log.debug('Approval disabled (no handler configured)');
+    // ── 6. Durability — auto-detect (deferred to init) ──────────────────
+    // Wrapping is only applied if the 'workflow' package is installed.
+    // Checked in ensureInit() since the detection is async.
+    // ── 7. ModelRetry — always on ─────────────────────────────────────────
+    tools = wrapAllToolsWithRetry(tools, 3);
+    log.debug('ModelRetry wrapping applied');
+    // ── 8. Auto-discover skills ───────────────────────────────────────────
+    let skillsPrompt = '';
+    try {
+        const discovered = discoverSkills(undefined, workspaceRoot);
+        const eligible = filterEligibleSkills(discovered);
+        if (eligible.length > 0) {
+            const loaded = eligible.map((s) => loadSkillContent(s));
+            skillsPrompt = buildSkillsSystemPrompt(loaded);
+            log.info('Skills discovered', { count: eligible.length, names: eligible.map((s) => s.name) });
+        }
+    }
+    catch (err) {
+        log.warn('Skill discovery failed', { error: err instanceof Error ? err.message : String(err) });
+    }
+    // ── 9. Build system prompt ────────────────────────────────────────────
+    let augmentedSystemPrompt = buildBaseInstructions(name, instructions, skillsPrompt);
+    // ── 10. Stop conditions ───────────────────────────────────────────────
+    const stopConditions = [
+        stepCountIs(maxSteps),
+    ];
+    if (options.usageLimits) {
+        stopConditions.push(usageLimitStop(options.usageLimits));
+        log.debug('Usage limits configured', { limits: options.usageLimits });
+    }
+    // ── 11. Reflection — always on (reflact strategy) ─────────────────────
+    const prepareStep = createReflectionPrepareStep(augmentedSystemPrompt, {
+        strategy: 'reflact',
+    });
+    log.debug('Reflection enabled', { strategy: 'reflact' });
+    // ── 12. Guardrails — always on (output: PII content filter) ──────────
+    // Default output guardrails run on the final text to catch PII leaks.
+    // Uses 'filter' mode: PII is silently redacted, not blocked.
+    const outputGuardrails = [contentFilter()];
+    log.debug('Output guardrails enabled', { guards: outputGuardrails.map((g) => g.name) });
+    // ── 13. Telemetry — auto-detect ──────────────────────────────────────
+    const telemetryEnabled = detectTelemetry();
+    const telemetrySettings = telemetryEnabled
+        ? createTelemetrySettings({ functionId: `agent-v2:${name}` })
+        : undefined;
+    if (telemetryEnabled) {
+        log.debug('Telemetry will be initialized on first call');
+    }
+    // ── 14. Build the ToolLoopAgent ───────────────────────────────────────
+    const toolLoopAgent = new ToolLoopAgent({
+        model,
+        instructions: augmentedSystemPrompt,
+        tools,
+        stopWhen: stopConditions,
+        // Dynamic system prompt injection — picks up memory context after lazy load
+        prepareCall: (opts) => ({ ...opts, instructions: augmentedSystemPrompt }),
+        prepareStep,
+        ...(telemetrySettings ? { experimental_telemetry: telemetrySettings } : {}),
+    });
+    log.debug('ToolLoopAgent created', {
+        promptLength: augmentedSystemPrompt.length,
+        toolCount: Object.keys(tools).length,
+        telemetry: !!telemetrySettings,
+    });
+    // ── Lazy initializers ─────────────────────────────────────────────────
+    const agentLog = log.child({ agent: name });
+    let initialized = false;
+    let initPromise = null;
+    async function ensureInit() {
+        if (initialized)
+            return;
+        if (initPromise)
+            return initPromise;
+        initPromise = (async () => {
+            // Load memory context into system prompt
+            try {
+                const memoryContext = await loadMemoryContext(memoryStore);
+                if (memoryContext) {
+                    augmentedSystemPrompt = memoryContext + '\n\n' + augmentedSystemPrompt;
+                    agentLog.debug('Memory context injected', { chars: memoryContext.length });
+                }
+            }
+            catch (err) {
+                agentLog.warn('Memory context loading failed', {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+            // Inject dynamic environment context (time, platform, workspace)
+            try {
+                augmentedSystemPrompt = await buildDynamicSystemPrompt(augmentedSystemPrompt, {
+                    workspaceRoot,
+                    includeWorkspaceMap: true,
+                });
+                agentLog.debug('Dynamic context injected');
+            }
+            catch (err) {
+                agentLog.warn('Dynamic context injection failed', {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+            // Apply durable wrapping if workflow runtime is available
+            try {
+                const workflowAvailable = await checkWorkflowAvailability();
+                if (workflowAvailable) {
+                    tools = wrapToolsAsDurable(tools, { retryCount: 3 });
+                    agentLog.info('Durable tool wrapping active (workflow package detected)');
+                }
+                else {
+                    agentLog.debug('Workflow package not installed — skipping durable wrapping');
+                }
+            }
+            catch {
+                agentLog.debug('Workflow detection failed — skipping durable wrapping');
+            }
+            // Initialize telemetry if detected
+            if (telemetryEnabled) {
+                try {
+                    await initObservability({
+                        provider: 'langfuse',
+                    });
+                    agentLog.info('Telemetry initialized');
+                }
+                catch (err) {
+                    agentLog.warn('Telemetry initialization failed', {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+            initialized = true;
+        })();
+        return initPromise;
+    }
+    // ── Build the agent instance ──────────────────────────────────────────
+    const agent = {
+        name,
+        init: ensureInit,
+        getSystemPrompt: () => augmentedSystemPrompt,
+        getToolNames: () => Object.keys(tools),
+        stream: async (input) => {
+            await ensureInit();
+            agentLog.info('stream() called', { promptLength: input.prompt.length });
+            const result = await toolLoopAgent.stream({ prompt: input.prompt });
+            // Apply output guardrails to the final text (async, runs after stream completes).
+            // Uses 'filter' mode — PII is silently redacted, agent is never blocked.
+            const guardedText = result.text.then(async (text) => {
+                if (!text || outputGuardrails.length === 0)
+                    return text;
+                try {
+                    const { results, filteredText } = await runGuardrails(outputGuardrails, text, {
+                        prompt: input.prompt,
+                        phase: 'output',
+                    });
+                    const check = handleGuardrailResults(results, text, filteredText, 'output', 'filter');
+                    if (check.blocked) {
+                        agentLog.info('Output guardrails filtered content', {
+                            guards: results.filter((r) => !r.passed).map((r) => r.name),
+                        });
+                        return check.text;
+                    }
+                }
+                catch (err) {
+                    agentLog.warn('Output guardrails failed', {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+                return text;
+            });
+            return {
+                fullStream: result.fullStream,
+                text: guardedText,
+                usage: result.totalUsage,
+            };
+        },
+    };
+    log.info('V2 agent created', {
+        name,
+        spawnDepth,
+        toolCount: Object.keys(tools).length,
+        tools: Object.keys(tools),
+        memoryPath: agentStatePath,
+        durable: 'auto-detect',
+        telemetry: telemetryEnabled,
+        reflection: 'reflact',
+        guardrails: outputGuardrails.map((g) => g.name),
+    });
+    return agent;
+}
+export default createAgentV2;
+//# sourceMappingURL=agent-v2.js.map

package/dist/agent-v2.js.map

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

package/dist/memory/engine.d.ts

@@ -0,0 +1,130 @@
+/**
+ * @agntk/core - Unified Memory Engine
+ *
+ * Single write path: remember() → LLM extraction → parallel writes to Vectra + Graph.
+ * Implements Mem0 ADD/UPDATE/DELETE/NOOP pattern with Hindsight 4-network taxonomy.
+ *
+ * Architecture:
+ * - VectorStore: Semantic similarity search (Vectra)
+ * - GraphStore: Structural relationships (Graphology via QueryPort)
+ * - ExtractionModel: LLM-powered fact extraction
+ * - ContradictionDetector: Write-time conflict detection
+ */
+import type { LanguageModel } from 'ai';
+import type { MemoryStore, MemorySearchResult } from './vectra-store.js';
+import { type ExtractedFact, type MemoryOperation } from './extraction.js';
+/** Graph store interface — matches QueryPort episode/entity methods */
+export interface MemoryGraphStore {
+    upsertEpisode(episode: {
+        id: string;
+        timestamp: string;
+        type: 'conversation' | 'observation' | 'action' | 'decision' | 'learning';
+        summary: string;
+        content: string;
+        entities: string[];
+        relationships: string[];
+    }): Promise<void>;
+    linkEpisodeEntity(episodeId: string, entityName: string): Promise<void>;
+    getEpisodesByQuery(query: string, limit: number): Promise<Array<{
+        id?: string;
+        summary?: string;
+        content?: string;
+        timestamp?: string;
+        type?: string;
+        properties?: Record<string, unknown>;
+    }>>;
+    upsertContradiction(contradiction: {
+        id: string;
+        detectedAt: string;
+        resolution_winner: string | null;
+        resolution_reasoning: string | null;
+        factA_id: string;
+        factA_statement: string;
+        factA_source: string;
+        factA_timestamp: string;
+        factB_id: string;
+        factB_statement: string;
+        factB_source: string;
+        factB_timestamp: string;
+    }): Promise<void>;
+}
+/** Contradiction detector interface — matches brain's ContradictionDetector */
+export interface ContradictionDetectorPort {
+    detect(statementA: string, statementB: string, metadataA?: {
+        id: string;
+        source: string;
+        timestamp: string;
+    }, metadataB?: {
+        id: string;
+        source: string;
+        timestamp: string;
+    }): {
+        id: string;
+        factA: Record<string, string>;
+        factB: Record<string, string>;
+        detectedAt: string;
+    } | null;
+}
+/** Result of a unified remember() operation */
+export interface MemoryWriteResult {
+    id: string;
+    operation: MemoryOperation;
+    facts: ExtractedFact[];
+    vectorStoreId?: string;
+    graphStoreId?: string;
+    contradiction?: {
+        id: string;
+        existingFact: string;
+        newFact: string;
+    };
+}
+/** Configuration for the unified memory engine */
+export interface MemoryEngineConfig {
+    /** Vector store for semantic search (Vectra) */
+    vectorStore: MemoryStore;
+    /** Graph store for structural queries (Graphology via QueryPort) — optional */
+    graphStore?: MemoryGraphStore;
+    /** LLM for extraction pipeline — optional, extraction disabled without it */
+    extractionModel?: LanguageModel;
+    /** Contradiction detector — optional */
+    contradictionDetector?: ContradictionDetectorPort;
+    /** Default top-K for recall */
+    defaultTopK?: number;
+    /** Default similarity threshold */
+    defaultThreshold?: number;
+}
+/** The unified memory engine interface */
+export interface MemoryEngine {
+    /** Store text with LLM extraction → parallel writes to vector + graph */
+    remember(text: string, metadata?: Record<string, unknown>): Promise<MemoryWriteResult>;
+    /** Semantic search via vector store */
+    recall(query: string, options?: {
+        topK?: number;
+        threshold?: number;
+    }): Promise<MemorySearchResult[]>;
+    /** Graph-based knowledge query — returns episodes/entities matching query */
+    queryKnowledge(query: string, limit?: number): Promise<Array<Record<string, unknown>>>;
+    /** Remove a memory by ID from both stores */
+    forget(id: string): Promise<boolean>;
+    /** Get stats */
+    count(): Promise<number>;
+    /** Cleanup */
+    close(): Promise<void>;
+}
+/**
+ * Create a unified memory engine.
+ *
+ * @example
+ * ```typescript
+ * const engine = createMemoryEngine({
+ *   vectorStore: await createMemoryStore({ path: './.memory' }),
+ *   graphStore: new GraphologyAdapter(),
+ *   extractionModel: openai('gpt-4o-mini'),
+ * });
+ *
+ * // Single remember() does extraction + parallel writes
+ * const result = await engine.remember('TypeScript 5.3 supports import attributes');
+ * ```
+ */
+export declare function createMemoryEngine(config: MemoryEngineConfig): MemoryEngine;
+//# sourceMappingURL=engine.d.ts.map

package/dist/memory/engine.d.ts.map

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