thinkwell 0.1.0

package/dist/schema.d.ts

@@ -0,0 +1,35 @@
+import type { JsonSchema, SchemaProvider } from "@thinkwell/acp";
+/**
+ * Creates a SchemaProvider from a raw JSON Schema object.
+ *
+ * This is a convenience function for users who want to pass a JSON schema
+ * directly without using a schema library like Zod or TypeBox.
+ *
+ * @typeParam T - The TypeScript type that this schema describes
+ * @param schema - A JSON Schema object describing the expected output structure
+ * @returns A SchemaProvider that wraps the given schema
+ *
+ * @example
+ * ```typescript
+ * interface Summary {
+ *   title: string;
+ *   points: string[];
+ * }
+ *
+ * const result = await patchwork
+ *   .think(schemaOf<Summary>({
+ *     type: "object",
+ *     properties: {
+ *       title: { type: "string" },
+ *       points: { type: "array", items: { type: "string" } }
+ *     },
+ *     required: ["title", "points"]
+ *   }))
+ *   .text("Summarize this document")
+ *   .run();
+ *
+ * // result is typed as Summary
+ * ```
+ */
+export declare function schemaOf<T>(schema: JsonSchema): SchemaProvider<T>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,GAAG,cAAc,CAAC,CAAC,CAAC,CAIjE"}

package/dist/schema.js

@@ -0,0 +1,38 @@
+/**
+ * Creates a SchemaProvider from a raw JSON Schema object.
+ *
+ * This is a convenience function for users who want to pass a JSON schema
+ * directly without using a schema library like Zod or TypeBox.
+ *
+ * @typeParam T - The TypeScript type that this schema describes
+ * @param schema - A JSON Schema object describing the expected output structure
+ * @returns A SchemaProvider that wraps the given schema
+ *
+ * @example
+ * ```typescript
+ * interface Summary {
+ *   title: string;
+ *   points: string[];
+ * }
+ *
+ * const result = await patchwork
+ *   .think(schemaOf<Summary>({
+ *     type: "object",
+ *     properties: {
+ *       title: { type: "string" },
+ *       points: { type: "array", items: { type: "string" } }
+ *     },
+ *     required: ["title", "points"]
+ *   }))
+ *   .text("Summarize this document")
+ *   .run();
+ *
+ * // result is typed as Summary
+ * ```
+ */
+export function schemaOf(schema) {
+    return {
+        toJsonSchema: () => schema,
+    };
+}
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,QAAQ,CAAI,MAAkB;IAC5C,OAAO;QACL,YAAY,EAAE,GAAG,EAAE,CAAC,MAAM;KAC3B,CAAC;AACJ,CAAC"}

package/dist/session.d.ts

@@ -0,0 +1,78 @@
+import type { AgentConnection, SessionOptions } from "./agent.js";
+import type { SchemaProvider } from "@thinkwell/acp";
+import { ThinkBuilder } from "./think-builder.js";
+/**
+ * A session for multi-turn conversations with an agent.
+ *
+ * Sessions maintain conversation context across multiple `think()` calls,
+ * allowing the agent to remember previous interactions. Create sessions
+ * using `agent.createSession()`.
+ *
+ * @example
+ * ```typescript
+ * const session = await agent.createSession({ cwd: "/my/project" });
+ *
+ * // First turn
+ * const analysis = await session
+ *   .think(AnalysisSchema)
+ *   .text("Analyze this codebase")
+ *   .run();
+ *
+ * // Second turn - agent remembers context
+ * const fixes = await session
+ *   .think(FixesSchema)
+ *   .text("Suggest fixes for the top issues")
+ *   .run();
+ *
+ * session.close();
+ * ```
+ */
+export declare class Session {
+    private readonly _conn;
+    private readonly _sessionId;
+    private readonly _options;
+    private _closed;
+    /**
+     * @internal
+     */
+    constructor(conn: AgentConnection, sessionId: string, options?: SessionOptions);
+    /**
+     * The unique session identifier
+     */
+    get sessionId(): string;
+    /**
+     * Create a new think builder for constructing a prompt with tools.
+     *
+     * Unlike `agent.think()`, prompts sent through a session maintain
+     * conversation context - the agent remembers previous interactions.
+     *
+     * @param schema - A SchemaProvider that defines the expected output structure
+     *
+     * @example
+     * ```typescript
+     * const result = await session
+     *   .think(schemaOf<{ answer: string }>({
+     *     type: "object",
+     *     properties: { answer: { type: "string" } },
+     *     required: ["answer"]
+     *   }))
+     *   .text("What was the first thing I asked you?")
+     *   .run();
+     * ```
+     */
+    think<Output>(schema: SchemaProvider<Output>): ThinkBuilder<Output>;
+    /**
+     * Create a new think builder without a schema.
+     *
+     * @deprecated Use `think(schemaOf<T>(schema))` instead to provide a typed schema.
+     */
+    think<Output>(): ThinkBuilder<Output>;
+    /**
+     * Close the session.
+     *
+     * After closing, no more prompts can be sent through this session.
+     * The agent connection remains open for other sessions.
+     */
+    close(): void;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IACtD,OAAO,CAAC,OAAO,CAAkB;IAEjC;;OAEG;gBACS,IAAI,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc;IAM9E;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC,GAAG,YAAY,CAAC,MAAM,CAAC;IAEnE;;;;OAIG;IACH,KAAK,CAAC,MAAM,KAAK,YAAY,CAAC,MAAM,CAAC;IASrC;;;;;OAKG;IACH,KAAK,IAAI,IAAI;CAKd"}

package/dist/session.js

@@ -0,0 +1,65 @@
+import { ThinkBuilder } from "./think-builder.js";
+/**
+ * A session for multi-turn conversations with an agent.
+ *
+ * Sessions maintain conversation context across multiple `think()` calls,
+ * allowing the agent to remember previous interactions. Create sessions
+ * using `agent.createSession()`.
+ *
+ * @example
+ * ```typescript
+ * const session = await agent.createSession({ cwd: "/my/project" });
+ *
+ * // First turn
+ * const analysis = await session
+ *   .think(AnalysisSchema)
+ *   .text("Analyze this codebase")
+ *   .run();
+ *
+ * // Second turn - agent remembers context
+ * const fixes = await session
+ *   .think(FixesSchema)
+ *   .text("Suggest fixes for the top issues")
+ *   .run();
+ *
+ * session.close();
+ * ```
+ */
+export class Session {
+    _conn;
+    _sessionId;
+    _options;
+    _closed = false;
+    /**
+     * @internal
+     */
+    constructor(conn, sessionId, options) {
+        this._conn = conn;
+        this._sessionId = sessionId;
+        this._options = options;
+    }
+    /**
+     * The unique session identifier
+     */
+    get sessionId() {
+        return this._sessionId;
+    }
+    think(schema) {
+        if (this._closed) {
+            throw new Error("Session is closed");
+        }
+        return new ThinkBuilder(this._conn, schema, this._sessionId);
+    }
+    /**
+     * Close the session.
+     *
+     * After closing, no more prompts can be sent through this session.
+     * The agent connection remains open for other sessions.
+     */
+    close() {
+        this._closed = true;
+        // Note: ACP doesn't have an explicit session close message,
+        // we just stop using the session ID
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,OAAO,OAAO;IACD,KAAK,CAAkB;IACvB,UAAU,CAAS;IACnB,QAAQ,CAA6B;IAC9C,OAAO,GAAY,KAAK,CAAC;IAEjC;;OAEG;IACH,YAAY,IAAqB,EAAE,SAAiB,EAAE,OAAwB;QAC5E,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC5B,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IA+BD,KAAK,CAAS,MAA+B;QAC3C,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;QACvC,CAAC;QACD,OAAO,IAAI,YAAY,CAAS,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IACvE,CAAC;IAED;;;;;OAKG;IACH,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,4DAA4D;QAC5D,oCAAoC;IACtC,CAAC;CACF"}

package/dist/think-builder.d.ts

@@ -0,0 +1,150 @@
+import { type JsonSchema, type SchemaProvider } from "@thinkwell/acp";
+import type { AgentConnection } from "./agent.js";
+/**
+ * Fluent builder for composing prompts with tools.
+ *
+ * ThinkBuilder provides a chainable API for:
+ * - Adding literal text to the prompt
+ * - Interpolating values
+ * - Registering tools the LLM can call
+ * - Executing the prompt and returning a typed result
+ */
+export declare class ThinkBuilder<Output> {
+    private readonly _conn;
+    private _promptParts;
+    private _tools;
+    private _schemaProvider;
+    private _cwd;
+    private _existingSessionId;
+    constructor(conn: AgentConnection, schema?: SchemaProvider<Output>, existingSessionId?: string);
+    /**
+     * Add literal text to the prompt
+     */
+    text(content: string): this;
+    /**
+     * Add a line of text with newline
+     */
+    textln(content: string): this;
+    /**
+     * Quote some content delimited by XML-style tags.
+     */
+    quote(content: string, tag?: string): this;
+    /**
+     * Quote some content as a Markdown-style code block.
+     */
+    code(content: string, language?: string): this;
+    /**
+     * Interpolate a value using toString()
+     *
+     * @deprecated Use `text()` or `quote()` instead for clearer intent.
+     */
+    display(value: unknown): this;
+    /**
+     * Register a tool and reference it in the prompt.
+     *
+     * The tool will be mentioned in the prompt text to help the LLM
+     * understand that it's available.
+     *
+     * @param name - The tool name
+     * @param description - A description of what the tool does
+     * @param inputSchema - A SchemaProvider describing the expected input structure
+     * @param outputSchema - A SchemaProvider describing the output structure
+     * @param handler - The function to execute when the tool is called
+     *
+     * @example
+     * ```typescript
+     * import { schemaOf } from "@dherman/patchwork";
+     *
+     * interface SearchInput {
+     *   query: string;
+     *   limit?: number;
+     * }
+     *
+     * interface SearchResult {
+     *   matches: string[];
+     *   total: number;
+     * }
+     *
+     * agent.think(outputSchema)
+     *   .tool(
+     *     "search",
+     *     "Search for documents",
+     *     schemaOf<SearchInput>({
+     *       type: "object",
+     *       properties: {
+     *         query: { type: "string" },
+     *         limit: { type: "number" }
+     *       },
+     *       required: ["query"]
+     *     }),
+     *     schemaOf<SearchResult>({
+     *       type: "object",
+     *       properties: {
+     *         matches: { type: "array", items: { type: "string" } },
+     *         total: { type: "number" }
+     *       },
+     *       required: ["matches", "total"]
+     *     }),
+     *     async (input: SearchInput) => { ... }
+     *   )
+     *   .run();
+     * ```
+     */
+    tool<I, O>(name: string, description: string, inputSchema: SchemaProvider<I>, outputSchema: SchemaProvider<O>, handler: (input: I) => Promise<O>): this;
+    /**
+     * Register a tool with only an input schema.
+     */
+    tool<I>(name: string, description: string, inputSchema: SchemaProvider<I>, handler: (input: I) => Promise<unknown>): this;
+    /**
+     * Register a tool without schemas.
+     */
+    tool(name: string, description: string, handler: (input: unknown) => Promise<unknown>): this;
+    /**
+     * Register a tool without adding a prompt reference.
+     *
+     * Use this for tools that should be available but don't need
+     * to be explicitly mentioned in the prompt.
+     *
+     * @param name - The tool name
+     * @param description - A description of what the tool does
+     * @param inputSchema - A SchemaProvider describing the expected input structure
+     * @param outputSchema - A SchemaProvider describing the output structure
+     * @param handler - The function to execute when the tool is called
+     */
+    defineTool<I, O>(name: string, description: string, inputSchema: SchemaProvider<I>, outputSchema: SchemaProvider<O>, handler: (input: I) => Promise<O>): this;
+    /**
+     * Register a tool with only an input schema (no prompt reference).
+     */
+    defineTool<I>(name: string, description: string, inputSchema: SchemaProvider<I>, handler: (input: I) => Promise<unknown>): this;
+    /**
+     * Register a tool without schemas (no prompt reference).
+     */
+    defineTool(name: string, description: string, handler: (input: unknown) => Promise<unknown>): this;
+    /**
+     * Set the expected output schema.
+     *
+     * This generates a return_result tool that the LLM must call
+     * to provide the final output.
+     *
+     * @deprecated Use `agent.think(schemaOf<T>(schema))` instead to provide a typed schema at construction time.
+     */
+    outputSchema(schema: JsonSchema): this;
+    /**
+     * Set the working directory for the session
+     */
+    cwd(path: string): this;
+    /**
+     * Execute the prompt and return the result.
+     *
+     * This method:
+     * 1. Builds the final prompt from all text parts
+     * 2. Creates an MCP server with all registered tools
+     * 3. Adds a return_result tool for the output
+     * 4. Sends the prompt to the agent
+     * 5. Handles tool calls until the agent returns a result
+     * 6. Returns the typed result
+     */
+    run(): Promise<Output>;
+    private _executeRun;
+}
+//# sourceMappingURL=think-builder.d.ts.map

package/dist/think-builder.d.ts.map

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