@hham21/circe 0.4.0 → 0.5.0

package/README.md

@@ -7,60 +7,46 @@ Inspired by Anthropic's [Harness Design for Long-Running Application Development
 ## Install
 
 ```bash
-git clone https://github.com/hham21/circe.git
-cd circe
-npm install
+npm install @hham21/circe
 ```
 
-Requires Node.js 22+ and [Claude Code](https://claude.ai/code) authenticated via OAuth or API key:
+Requires Node.js 22+ and a Claude API key:
 
 ```bash
 export ANTHROPIC_API_KEY=sk-ant-...
 ```
 
-Run examples with `npx tsx` (see [examples/README.md](examples/README.md) for the full list):
-
-```bash
-npx tsx examples/01-single-agent.ts
-npx tsx examples/06-compose.ts    # the money shot — nested primitives
-```
-
 ## Quick Start
 
 ```typescript
-import { Pipeline, Loop, agent } from "circe";
+import { Agent, Loop, Session } from "@hham21/circe";
 
-const planner = agent({
-  name: "planner",
-  prompt: "Expand the user prompt into a detailed product spec.",
-});
-
-const generator = agent({
+const generator = new Agent({
   name: "generator",
   prompt: "Build the app based on the spec or QA feedback.",
+  model: "claude-sonnet-4-6",
 });
 
-const evaluator = agent({
+const evaluator = new Agent({
   name: "evaluator",
-  prompt: "Test the app with Playwright. FAIL with feedback if issues found.",
-  tools: ["Read", "Bash", "Glob", "Grep"],
-  skills: ["qa", "browse"],
+  prompt: "Test the app. FAIL with feedback if issues found.",
+  model: "claude-opus-4-6",
 });
 
-const app = new Pipeline(
-  planner,
-  new Loop(generator, evaluator, { maxRounds: 3, stopWhen: (r: any) => r.passed }),
-);
+const loop = new Loop(generator, evaluator, { maxRounds: 3 });
 
-await app.run("Build a retro game maker");
+await new Session({ outputDir: "./output", verbose: true })
+  .run(() => loop.run("Build a retro game maker"));
 ```
 
+See [examples/](examples/README.md) for 14 progressive examples (`npx tsx examples/01-single-agent.ts`).
+
 ## Concepts
 
 ### Agents
 
 ```typescript
-import { Agent, agent } from "circe";
+import { Agent, agent } from "@hham21/circe";
 
 // Factory function (simple)
 const reviewer = agent({
@@ -73,13 +59,14 @@ const reviewer = agent({
 const evaluator = new Agent({
   name: "evaluator",
   prompt: "Strict QA engineer.",
+  model: "claude-opus-4-6",
   tools: ["Read", "Bash"],
   skills: ["qa"],
   contextStrategy: "reset",
 });
 ```
 
-All Claude Agent SDK built-in tools (Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch, Agent) are available by default. Restrict with `tools`.
+All Claude Agent SDK built-in tools (Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch, Agent) are available by default. Restrict with `tools`. Set `model` per agent to control cost/capability.
 
 ### Orchestrators
 
@@ -98,7 +85,7 @@ Loop and Contract return **producer output on success** (the content, not the ev
 Compose freely:
 
 ```typescript
-import { pipe } from "circe";
+import { pipe } from "@hham21/circe";
 
 // Type-safe pipeline — compiler checks that output types chain correctly
 pipe(planner, new Loop(generator, evaluator, { maxRounds: 3 }));
@@ -107,10 +94,25 @@ pipe(planner, new Loop(generator, evaluator, { maxRounds: 3 }));
 pipe(planner, new Contract(proposer, reviewer), new Loop(generator, evaluator));
 ```
 
+### Session
+
+Session eliminates boilerplate. It auto-creates the output directory, sets up logging, initializes the skill registry, and cleans up when done. Context propagates through any orchestrator nesting via `AsyncLocalStorage`.
+
+```typescript
+import { Session } from "@hham21/circe";
+
+const session = new Session({ outputDir: "./output/my-app", verbose: true });
+await session.run(() => pipeline.run("Build a todo app"));
+
+console.log(`Duration: ${session.duration.toFixed(1)}s`);
+```
+
+Without Session, you can still use the global setters (`setFormatter`, `setWorkDir`, `setSkillRegistry`) directly.
+
 ### Tools
 
 ```typescript
-import { tool } from "circe";
+import { tool } from "@hham21/circe";
 
 const searchNpm = tool(function searchNpm(query: string): string {
   // Search npm packages
@@ -128,7 +130,7 @@ Skills are on-demand prompt templates. Agents load them when needed:
 const evaluator = agent({
   name: "evaluator",
   prompt: "QA engineer.",
-  skills: ["qa", "browse"],
+  skills: ["qa"],
 });
 ```
 
@@ -153,24 +155,19 @@ Zod schemas for structured agent-to-agent data passing:
 
 ```bash
 # Run a workflow file
-circe run workflow.js -i "prompt or spec file"
-
-# Agent management
-circe agents create my-reviewer --prompt "Review code." --tools "Read,Grep"
-circe agents list
-circe agents info my-reviewer
-circe agents delete my-reviewer
-
-# Workflow management
-circe workflows create my-pipe --agents "planner,generator,evaluator"
-circe workflows list
-circe workflows delete my-pipe
+circe run workflow.js -i "prompt or spec file" -v
+
+# Skill management
+circe skills list
+circe skills create my-skill
+circe skills info my-skill
 ```
 
 ## Architecture
 
 ```
-CLI Layer          circe run, agents, workflows
+Session Layer      Session (AsyncLocalStorage context propagation)
+CLI Layer          circe run, skills
 Orchestration      Pipeline, Loop, Parallel, Sprint, Contract
 Agent Layer        Agent, agent(), Handoff, Context Strategy
 Tool Layer         SDK built-ins, tool(), MCP servers, Skills

package/dist/cli/index.js

@@ -12,14 +12,12 @@ program
     .description("Run a workflow file")
     .requiredOption("-i, --input <input>", "User input or path to spec file")
     .option("-o, --output <dir>", "Output directory")
-    .option("-r, --max-rounds <n>", "Maximum rounds", parseInt)
     .option("-v, --verbose", "Verbose output")
     .action(async (workflow, opts) => {
     await executeWorkflow({
         workflow,
         input: opts.input,
         outputDir: opts.output,
-        maxRounds: opts.maxRounds,
         verbose: opts.verbose,
     });
 });

package/dist/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAShD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,OAAO,CAAC;KACb,WAAW,CAAC,4DAA4D,CAAC;KACzE,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpB,OAAO;KACJ,OAAO,CAAC,gBAAgB,CAAC;KACzB,WAAW,CAAC,qBAAqB,CAAC;KAClC,cAAc,CAAC,qBAAqB,EAAE,iCAAiC,CAAC;KACxE,MAAM,CAAC,oBAAoB,EAAE,kBAAkB,CAAC;KAChD,MAAM,CAAC,sBAAsB,EAAE,gBAAgB,EAAE,QAAQ,CAAC;KAC1D,MAAM,CAAC,eAAe,EAAE,gBAAgB,CAAC;KACzC,MAAM,CAAC,KAAK,EAAE,QAAgB,EAAE,IAAgB,EAAE,EAAE;IACnD,MAAM,eAAe,CAAC;QACpB,QAAQ;QACR,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,SAAS,EAAE,IAAI,CAAC,MAAM;QACtB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,OAAO,EAAE,IAAI,CAAC,OAAO;KACtB,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEL,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAElC,OAAO,EAAE,OAAO,EAAE,CAAC;AAEnB,OAAO,CAAC,KAAK,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAQhD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,OAAO,CAAC;KACb,WAAW,CAAC,4DAA4D,CAAC;KACzE,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpB,OAAO;KACJ,OAAO,CAAC,gBAAgB,CAAC;KACzB,WAAW,CAAC,qBAAqB,CAAC;KAClC,cAAc,CAAC,qBAAqB,EAAE,iCAAiC,CAAC;KACxE,MAAM,CAAC,oBAAoB,EAAE,kBAAkB,CAAC;KAChD,MAAM,CAAC,eAAe,EAAE,gBAAgB,CAAC;KACzC,MAAM,CAAC,KAAK,EAAE,QAAgB,EAAE,IAAgB,EAAE,EAAE;IACnD,MAAM,eAAe,CAAC;QACpB,QAAQ;QACR,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,SAAS,EAAE,IAAI,CAAC,MAAM;QACtB,OAAO,EAAE,IAAI,CAAC,OAAO;KACtB,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEL,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAElC,OAAO,EAAE,OAAO,EAAE,CAAC;AAEnB,OAAO,CAAC,KAAK,EAAE,CAAC"}

package/dist/cli/run.d.ts

@@ -2,7 +2,6 @@ export declare function executeWorkflow(options: {
     workflow: string;
     input: string;
     outputDir?: string;
-    maxRounds?: number;
     verbose?: boolean;
 }): Promise<void>;
 export declare function slugify(text: string): string;

package/dist/cli/run.js

@@ -1,26 +1,24 @@
-import { existsSync, readFileSync, mkdirSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { OutputFormatter } from "./output.js";
-import { setFormatter, setWorkDir, setSkillRegistry } from "../context.js";
-import { SkillRegistry } from "../tools/skills.js";
+import { Session } from "../session.js";
 const SLUG_MAX_LENGTH = 50;
 export async function executeWorkflow(options) {
-    const { workflow, input: rawInput, outputDir, maxRounds, verbose } = options;
+    const { workflow, input: rawInput, outputDir, verbose } = options;
     const userInput = resolveInput(rawInput);
-    const workDir = resolveWorkDir(userInput, outputDir);
-    const formatter = initializeContext(workDir, verbose);
-    const startTime = Date.now();
-    try {
-        const runner = await loadWorkflowFile(workflow);
-        const result = await runner.run(userInput);
-        formatter.logResult(serializeResult(result));
-    }
-    finally {
-        const elapsedSeconds = (Date.now() - startTime) / 1000;
-        formatter.finalSummary(workDir, elapsedSeconds);
-        formatter.close();
-        teardownContext();
-    }
+    const slug = slugify(userInput);
+    const baseOutput = outputDir ?? resolve("output");
+    const outDir = findUniqueOutputDir(baseOutput, slug);
+    const session = new Session({ outputDir: outDir, verbose });
+    await session.run(async () => {
+        try {
+            const runner = await loadWorkflowFile(workflow);
+            const result = await runner.run(userInput);
+            session.formatter.logResult(serializeResult(result));
+        }
+        finally {
+            session.formatter.finalSummary(outDir, session.duration);
+        }
+    });
 }
 export function slugify(text) {
     return text
@@ -47,33 +45,6 @@ export function findUniqueOutputDir(base, slug) {
     }
     return join(base, `${slug}-${counter}`);
 }
-function resolveWorkDir(userInput, outputDir) {
-    const slug = slugify(userInput);
-    const baseOutput = outputDir ?? resolve("output");
-    const workDir = findUniqueOutputDir(baseOutput, slug);
-    mkdirSync(workDir, { recursive: true });
-    return workDir;
-}
-function initializeContext(workDir, verbose) {
-    const formatter = new OutputFormatter(verbose);
-    formatter.setLogFile(join(workDir, "circe.log"));
-    setFormatter(formatter);
-    setWorkDir(workDir);
-    setSkillRegistry(createSkillRegistry(workDir));
-    return formatter;
-}
-function createSkillRegistry(workDir) {
-    const skillDirs = [
-        join(workDir, ".circe", "skills"),
-        join(process.env.HOME, ".circe", "skills"),
-    ];
-    return new SkillRegistry(skillDirs);
-}
-function teardownContext() {
-    setFormatter(null);
-    setWorkDir(null);
-    setSkillRegistry(null);
-}
 async function loadWorkflowFile(path) {
     const mod = await import(resolve(path));
     if (typeof mod.default?.run === "function")

package/dist/cli/run.js.map

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

package/dist/context.js

@@ -1,4 +1,5 @@
-// Module-level singletons shared across the agent session
+import { sessionStore } from "./session.js";
+// Module-level singletons shared across the agent session (legacy fallback)
 let formatter = null;
 let workDir = null;
 let skillRegistry = null;
@@ -6,18 +7,18 @@ export function setFormatter(value) {
     formatter = value;
 }
 export function getFormatter() {
-    return formatter;
+    return sessionStore.getStore()?.formatter ?? formatter;
 }
 export function setWorkDir(value) {
     workDir = value;
 }
 export function getWorkDir() {
-    return workDir;
+    return sessionStore.getStore()?.workDir ?? workDir;
 }
 export function setSkillRegistry(value) {
     skillRegistry = value;
 }
 export function getSkillRegistry() {
-    return skillRegistry;
+    return sessionStore.getStore()?.skillRegistry ?? skillRegistry;
 }
 //# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAGA,0DAA0D;AAC1D,IAAI,SAAS,GAA2B,IAAI,CAAC;AAC7C,IAAI,OAAO,GAAkB,IAAI,CAAC;AAClC,IAAI,aAAa,GAAyB,IAAI,CAAC;AAE/C,MAAM,UAAU,YAAY,CAAC,KAA6B;IACxD,SAAS,GAAG,KAAK,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAoB;IAC7C,OAAO,GAAG,KAAK,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAA2B;IAC1D,aAAa,GAAG,KAAK,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO,aAAa,CAAC;AACvB,CAAC"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,4EAA4E;AAC5E,IAAI,SAAS,GAA2B,IAAI,CAAC;AAC7C,IAAI,OAAO,GAAkB,IAAI,CAAC;AAClC,IAAI,aAAa,GAAyB,IAAI,CAAC;AAE/C,MAAM,UAAU,YAAY,CAAC,KAA6B;IACxD,SAAS,GAAG,KAAK,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,OAAO,YAAY,CAAC,QAAQ,EAAE,EAAE,SAAS,IAAI,SAAS,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAoB;IAC7C,OAAO,GAAG,KAAK,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,OAAO,YAAY,CAAC,QAAQ,EAAE,EAAE,OAAO,IAAI,OAAO,CAAC;AACrD,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAA2B;IAC1D,aAAa,GAAG,KAAK,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO,YAAY,CAAC,QAAQ,EAAE,EAAE,aAAa,IAAI,aAAa,CAAC;AACjE,CAAC"}

package/dist/index.d.ts

@@ -5,5 +5,7 @@ export { FeatureSchema, TechStackSchema, ProductSpecSchema, BuildResultSchema, Q
 export { Pipeline, pipe, Loop, Parallel, Contract, Sprint, type PipelineOptions, type LoopOptions, type ParallelOptions, type ParallelResult, type ContractOptions, type SprintOptions, } from "./orchestration/index.js";
 export { OutputFormatter } from "./cli/output.js";
 export { SkillRegistry, type SkillInfo } from "./tools/skills.js";
-export { setFormatter, setSkillRegistry, getSkillRegistry } from "./context.js";
+export { Session, type SessionOptions } from "./session.js";
+export { setFormatter, setWorkDir, setSkillRegistry, getSkillRegistry } from "./context.js";
+export { PLAYWRIGHT_MCP_SERVER } from "./utils.js";
 export { RunContextSchema, type RunContext, type Runnable, type MetricsSnapshot } from "./types.js";

package/dist/index.js

@@ -5,6 +5,8 @@ export { FeatureSchema, TechStackSchema, ProductSpecSchema, BuildResultSchema, Q
 export { Pipeline, pipe, Loop, Parallel, Contract, Sprint, } from "./orchestration/index.js";
 export { OutputFormatter } from "./cli/output.js";
 export { SkillRegistry } from "./tools/skills.js";
-export { setFormatter, setSkillRegistry, getSkillRegistry } from "./context.js";
+export { Session } from "./session.js";
+export { setFormatter, setWorkDir, setSkillRegistry, getSkillRegistry } from "./context.js";
+export { PLAYWRIGHT_MCP_SERVER } from "./utils.js";
 export { RunContextSchema } from "./types.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,IAAI,SAAS,EAAE,KAAK,EAAE,SAAS,EAAsB,MAAM,YAAY,CAAC;AAC7F,OAAO,EACL,QAAQ,EACR,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,GAGf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,aAAa,EAAE,iBAAiB,EAA2B,MAAM,YAAY,CAAC;AAC7H,OAAO,EACL,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EAMd,WAAW,GACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,QAAQ,EACR,IAAI,EACJ,IAAI,EACJ,QAAQ,EACR,QAAQ,EACR,MAAM,GAOP,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAkB,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChF,OAAO,EAAE,gBAAgB,EAAwD,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,IAAI,SAAS,EAAE,KAAK,EAAE,SAAS,EAAsB,MAAM,YAAY,CAAC;AAC7F,OAAO,EACL,QAAQ,EACR,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,GAGf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,aAAa,EAAE,iBAAiB,EAA2B,MAAM,YAAY,CAAC;AAC7H,OAAO,EACL,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EAMd,WAAW,GACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,QAAQ,EACR,IAAI,EACJ,IAAI,EACJ,QAAQ,EACR,QAAQ,EACR,MAAM,GAOP,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAkB,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAE,OAAO,EAAuB,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC5F,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAwD,MAAM,YAAY,CAAC"}

package/dist/session.d.ts

@@ -0,0 +1,21 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { OutputFormatter } from "./cli/output.js";
+import { SkillRegistry } from "./tools/skills.js";
+export interface SessionOptions {
+    outputDir?: string;
+    verbose?: boolean;
+    skills?: string[];
+}
+export declare class Session {
+    workDir: string;
+    formatter: OutputFormatter;
+    skillRegistry: SkillRegistry;
+    private startTime;
+    private endTime;
+    constructor(options?: SessionOptions);
+    run<T>(fn: () => Promise<T>): Promise<T>;
+    get duration(): number;
+    private createDefaultSkillRegistry;
+    private teardown;
+}
+export declare const sessionStore: AsyncLocalStorage<Session>;

package/dist/session.js

@@ -0,0 +1,57 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { OutputFormatter } from "./cli/output.js";
+import { SkillRegistry } from "./tools/skills.js";
+import { circeHome } from "./utils.js";
+export class Session {
+    workDir;
+    formatter;
+    skillRegistry;
+    startTime = null;
+    endTime = null;
+    constructor(options = {}) {
+        this.workDir = resolve(options.outputDir ?? process.cwd());
+        mkdirSync(this.workDir, { recursive: true });
+        this.formatter = new OutputFormatter(options.verbose);
+        this.formatter.setLogFile(join(this.workDir, "circe.log"));
+        this.skillRegistry = options.skills
+            ? new SkillRegistry(options.skills)
+            : this.createDefaultSkillRegistry();
+    }
+    async run(fn) {
+        this.startTime = Date.now();
+        return sessionStore.run(this, async () => {
+            try {
+                return await fn();
+            }
+            finally {
+                this.endTime = Date.now();
+                this.teardown();
+            }
+        });
+    }
+    get duration() {
+        if (this.startTime == null)
+            return 0;
+        const end = this.endTime ?? Date.now();
+        return (end - this.startTime) / 1000;
+    }
+    createDefaultSkillRegistry() {
+        const dirs = [
+            join(this.workDir, ".circe", "skills"),
+            join(circeHome(), "skills"),
+        ];
+        return new SkillRegistry(dirs);
+    }
+    teardown() {
+        try {
+            this.formatter.close();
+        }
+        catch (err) {
+            console.error("[session] teardown error:", err);
+        }
+    }
+}
+export const sessionStore = new AsyncLocalStorage();
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAQvC,MAAM,OAAO,OAAO;IAClB,OAAO,CAAS;IAChB,SAAS,CAAkB;IAC3B,aAAa,CAAgB;IACrB,SAAS,GAAkB,IAAI,CAAC;IAChC,OAAO,GAAkB,IAAI,CAAC;IAEtC,YAAY,UAA0B,EAAE;QACtC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QAC3D,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAE7C,IAAI,CAAC,SAAS,GAAG,IAAI,eAAe,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACtD,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC;QAE3D,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,MAAM;YACjC,CAAC,CAAC,IAAI,aAAa,CAAC,OAAO,CAAC,MAAM,CAAC;YACnC,CAAC,CAAC,IAAI,CAAC,0BAA0B,EAAE,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,GAAG,CAAI,EAAoB;QAC/B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE5B,OAAO,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,IAAI,EAAE;YACvC,IAAI,CAAC;gBACH,OAAO,MAAM,EAAE,EAAE,CAAC;YACpB,CAAC;oBAAS,CAAC;gBACT,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;gBAC1B,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,IAAI,QAAQ;QACV,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI;YAAE,OAAO,CAAC,CAAC;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;QACvC,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;IACvC,CAAC;IAEO,0BAA0B;QAChC,MAAM,IAAI,GAAG;YACX,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC;YACtC,IAAI,CAAC,SAAS,EAAE,EAAE,QAAQ,CAAC;SAC5B,CAAC;QACF,OAAO,IAAI,aAAa,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAEO,QAAQ;QACd,IAAI,CAAC;YACH,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QACzB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,2BAA2B,EAAE,GAAG,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;CACF;AAED,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,iBAAiB,EAAW,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hham21/circe",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "GAN-style multi-agent framework for application generation using Claude Agent SDK",
   "type": "module",
   "main": "dist/index.js",