pocket-agent 0.1.0

package/dist/types/step.js

@@ -0,0 +1,5 @@
+/**
+ * Step execution and evaluation types (spec §9.7–9.10).
+ */
+export {};
+//# sourceMappingURL=step.js.map

package/dist/types/step.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"step.js","sourceRoot":"","sources":["../../src/types/step.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/types/tools.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Tool adapter contract (spec §13).
+ */
+import type { JsonSchemaLike } from "./plan.js";
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema?: JsonSchemaLike;
+    outputSchema?: JsonSchemaLike;
+}
+export interface ToolInvocationContext {
+    runId: string;
+    stepId: string;
+    attempt: number;
+    [key: string]: unknown;
+}
+export interface ToolAdapter {
+    definition: ToolDefinition;
+    invoke(input: unknown, context: ToolInvocationContext): Promise<unknown>;
+}
+//# sourceMappingURL=tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/types/tools.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,cAAc,CAAC;IAC7B,YAAY,CAAC,EAAE,cAAc,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,cAAc,CAAC;IAC3B,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1E"}

package/dist/types/tools.js

@@ -0,0 +1,5 @@
+/**
+ * Tool adapter contract (spec §13).
+ */
+export {};
+//# sourceMappingURL=tools.js.map

package/dist/types/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/types/tools.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/utils/dag.d.ts

@@ -0,0 +1,18 @@
+/**
+ * DAG utilities for plan steps: ready steps, cycle detection, topological order.
+ */
+import type { StepDefinition } from "../types/plan.js";
+/**
+ * Returns step IDs that have all dependencies satisfied (in completedStepIds).
+ * Steps with no dependencies are ready when completedStepIds is empty.
+ */
+export declare function getReadySteps(steps: StepDefinition[], completedStepIds: Set<string>): string[];
+/**
+ * Detects if the step graph has a cycle. Returns true if cycle exists.
+ */
+export declare function hasCycle(steps: StepDefinition[]): boolean;
+/**
+ * Topological sort of step IDs. Throws if cycle detected.
+ */
+export declare function topologicalSort(steps: StepDefinition[]): string[];
+//# sourceMappingURL=dag.d.ts.map

package/dist/utils/dag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dag.d.ts","sourceRoot":"","sources":["../../src/utils/dag.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,cAAc,EAAE,EACvB,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,GAC5B,MAAM,EAAE,CAWV;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,OAAO,CAwBzD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,MAAM,EAAE,CAwBjE"}

package/dist/utils/dag.js

@@ -0,0 +1,77 @@
+/**
+ * DAG utilities for plan steps: ready steps, cycle detection, topological order.
+ */
+/**
+ * Returns step IDs that have all dependencies satisfied (in completedStepIds).
+ * Steps with no dependencies are ready when completedStepIds is empty.
+ */
+export function getReadySteps(steps, completedStepIds) {
+    const stepMap = new Map(steps.map((s) => [s.id, s]));
+    const ready = [];
+    for (const step of steps) {
+        const deps = step.dependencies ?? [];
+        const allSatisfied = deps.every((depId) => completedStepIds.has(depId));
+        if (allSatisfied) {
+            ready.push(step.id);
+        }
+    }
+    return ready;
+}
+/**
+ * Detects if the step graph has a cycle. Returns true if cycle exists.
+ */
+export function hasCycle(steps) {
+    const stepMap = new Map(steps.map((s) => [s.id, s]));
+    const visited = new Set();
+    const stack = new Set();
+    function visit(id) {
+        if (stack.has(id))
+            return true;
+        if (visited.has(id))
+            return false;
+        visited.add(id);
+        stack.add(id);
+        const step = stepMap.get(id);
+        if (step) {
+            for (const depId of step.dependencies ?? []) {
+                if (visit(depId))
+                    return true;
+            }
+        }
+        stack.delete(id);
+        return false;
+    }
+    for (const step of steps) {
+        if (visit(step.id))
+            return true;
+    }
+    return false;
+}
+/**
+ * Topological sort of step IDs. Throws if cycle detected.
+ */
+export function topologicalSort(steps) {
+    if (hasCycle(steps)) {
+        throw new Error("Plan contains a cycle in step dependencies");
+    }
+    const stepMap = new Map(steps.map((s) => [s.id, s]));
+    const visited = new Set();
+    const result = [];
+    function visit(id) {
+        if (visited.has(id))
+            return;
+        visited.add(id);
+        const step = stepMap.get(id);
+        if (step) {
+            for (const depId of step.dependencies ?? []) {
+                visit(depId);
+            }
+        }
+        result.push(id);
+    }
+    for (const step of steps) {
+        visit(step.id);
+    }
+    return result;
+}
+//# sourceMappingURL=dag.js.map

package/dist/utils/dag.js.map

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

package/dist/utils/ids.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Unique ID generation for runs and steps.
+ */
+export declare function createRunId(): string;
+export declare function createStepId(prefix?: string): string;
+//# sourceMappingURL=ids.d.ts.map

package/dist/utils/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../src/utils/ids.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,wBAAgB,YAAY,CAAC,MAAM,SAAS,GAAG,MAAM,CAEpD"}

package/dist/utils/ids.js

@@ -0,0 +1,11 @@
+/**
+ * Unique ID generation for runs and steps.
+ */
+import { randomUUID } from "node:crypto";
+export function createRunId() {
+    return randomUUID();
+}
+export function createStepId(prefix = "step") {
+    return `${prefix}_${randomUUID().replace(/-/g, "").slice(0, 12)}`;
+}
+//# sourceMappingURL=ids.js.map

package/dist/utils/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../src/utils/ids.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,UAAU,WAAW;IACzB,OAAO,UAAU,EAAE,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAAM,GAAG,MAAM;IAC1C,OAAO,GAAG,MAAM,IAAI,UAAU,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;AACpE,CAAC"}

package/dist/utils/schema.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Optional JSON-schema validation helpers for step outputs (v1: minimal).
+ */
+import type { JsonSchemaLike } from "../types/plan.js";
+/**
+ * Stub: in v1 we do not validate against JSON schema by default.
+ * Can be extended to use a small library (e.g. ajv) if requireStructuredOutputs is used.
+ */
+export declare function validateOutput(_output: unknown, _schema: JsonSchemaLike): {
+    valid: true;
+} | {
+    valid: false;
+    errors: string[];
+};
+//# sourceMappingURL=schema.d.ts.map

package/dist/utils/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/utils/schema.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,cAAc,GACtB;IAAE,KAAK,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAEtD"}

package/dist/utils/schema.js

@@ -0,0 +1,11 @@
+/**
+ * Optional JSON-schema validation helpers for step outputs (v1: minimal).
+ */
+/**
+ * Stub: in v1 we do not validate against JSON schema by default.
+ * Can be extended to use a small library (e.g. ajv) if requireStructuredOutputs is used.
+ */
+export function validateOutput(_output, _schema) {
+    return { valid: true };
+}
+//# sourceMappingURL=schema.js.map

package/dist/utils/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/utils/schema.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAgB,EAChB,OAAuB;IAEvB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACzB,CAAC"}

package/dist/utils/time.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Timestamps and duration helpers.
+ */
+export declare function nowISO(): string;
+export declare function durationMs(startedAt: string, completedAt: string): number;
+//# sourceMappingURL=time.d.ts.map

package/dist/utils/time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.d.ts","sourceRoot":"","sources":["../../src/utils/time.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,wBAAgB,MAAM,IAAI,MAAM,CAE/B;AAED,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAEzE"}

package/dist/utils/time.js

@@ -0,0 +1,10 @@
+/**
+ * Timestamps and duration helpers.
+ */
+export function nowISO() {
+    return new Date().toISOString();
+}
+export function durationMs(startedAt, completedAt) {
+    return new Date(completedAt).getTime() - new Date(startedAt).getTime();
+}
+//# sourceMappingURL=time.js.map

package/dist/utils/time.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.js","sourceRoot":"","sources":["../../src/utils/time.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,UAAU,MAAM;IACpB,OAAO,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,SAAiB,EAAE,WAAmB;IAC/D,OAAO,IAAI,IAAI,CAAC,WAAW,CAAC,CAAC,OAAO,EAAE,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC;AACzE,CAAC"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "pocket-agent",
+  "version": "0.1.0",
+  "description": "Reusable Node.js framework for plan-driven agent execution",
+  "author": "sam_thewise",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "url": "https://github.com/sam-thewise/pocket-agent",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "example": "tsx examples/run-example.ts",
+    "example:openai": "tsx examples/run-with-openai.ts",
+    "example:planner": "tsx examples/run-project-planner.ts",
+    "example:quick-start": "tsx examples/run-quick-start.ts",
+    "example:fluent-plan": "tsx examples/run-fluent-plan.ts",
+    "example:goal-driven-llm": "tsx examples/run-goal-driven-llm.ts",
+    "example:minimal": "tsx examples/run-minimal.ts",
+    "lint": "eslint src --ext .ts"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "optionalDependencies": {
+    "@anthropic-ai/sdk": "^0.30.0",
+    "@google/genai": "^1.0.0",
+    "openai": "^4.52.0"
+  },
+  "devDependencies": {
+    "@anthropic-ai/sdk": "^0.30.0",
+    "@google/genai": "^1.0.0",
+    "@types/node": "^20.10.0",
+    "openai": "^4.52.0",
+    "typescript": "^5.3.0",
+    "tsx": "^4.7.0",
+    "vitest": "^1.2.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}