thoughtgear 0.1.2 → 0.1.3

package/README.md

@@ -247,6 +247,118 @@ Adapter status:
 - `memory`, `files`, `s3` — fully implemented.
 - `mongodb`, `sql` — stubbed in `src/classes/PromptHandler.ts`; fill in the eight `OrmAdapter` methods using the `mongodb` / `pg` / `kysely` drivers to make them live. Mongo collections used: `messages`, `run_states`, `cache`, `memory`.
 
+## Executors
+
+Each iteration of the agent loop is **stateless against the ORM** — the run, transcript, and tool results are persisted before the iteration returns. An **Executor** decides *how* the next iteration gets driven. Same loop semantics either way; the choice is operational.
+
+```ts
+interface Executor {
+  scheduleNextIteration(runId: string): Promise<void>;
+}
+```
+
+Two are built in. You pass one via `executor` on the constructor; the default is `LocalExecutor`.
+
+### `LocalExecutor` (default)
+
+Drives the next iteration in the same process by awaiting `handler.continueRun(runId)`. This is what you want for any single-process app — a script, a server handling a request end-to-end, a CLI, tests.
+
+```ts
+import { PromptHandler, LocalExecutor } from "thoughtgear";
+
+const handler = new PromptHandler({
+  context: "...",
+  tools: [...],
+  model: { ... },
+  db: { type: "memory" },
+  // executor: new LocalExecutor(),   // implicit — this is the default
+});
+
+await handler.handlePrompt({ text: "..." });   // resolves when the whole run finishes
+```
+
+`handlePrompt` / `continueRun` resolve only once the model is done iterating, so callers can `await` the full run.
+
+### `LambdaExecutor`
+
+Persists state, fires a **fresh invocation** of your Lambda with `{ runId, action: "continue" }`, and returns immediately. The next tick of the loop runs in a new invocation that loads state from the shared ORM.
+
+```ts
+import { PromptHandler, LambdaExecutor, makeLambdaHandler } from "thoughtgear";
+import { LambdaClient, InvokeCommand } from "@aws-sdk/client-lambda";
+
+const lambda = new LambdaClient({});
+const executor = new LambdaExecutor(async (payload) => {
+  await lambda.send(new InvokeCommand({
+    FunctionName: process.env.SELF_FUNCTION_NAME!,   // this function's own ARN/name
+    InvocationType: "Event",                          // fire-and-forget
+    Payload: Buffer.from(JSON.stringify(payload)),
+  }));
+});
+
+const handler = new PromptHandler({
+  context: "...",
+  tools: [...],
+  model: { ... },
+  db: { type: "s3", bucket: "my-bucket", path: "thoughtgear/prod" },
+  executor,
+});
+
+export const lambdaHandler = makeLambdaHandler(handler);
+```
+
+`makeLambdaHandler` routes events for you:
+
+```ts
+type LambdaEvent =
+  | { action: "start";    text: string; files?: FileAttachment[] }
+  | { action: "continue"; runId: string };
+```
+
+So one Lambda function serves both the initial prompt (`action: "start"`) and every continuation tick (`action: "continue"`).
+
+Requirements:
+- **Shared persistence.** Use `s3`, `mongodb`, or `sql` — `memory` won't survive an invocation boundary and `files` is single-host.
+- **Self-invoke permission.** The Lambda's IAM role needs `lambda:InvokeFunction` on its own ARN, plus whatever the persistence adapter needs.
+- **Idempotency.** With fire-and-forget invocations, an upstream retry could in theory schedule the same `runId` twice; the ORM has no atomic compare-and-swap on `files`/`s3`. In practice this is rare, but worth knowing if you're at high volume.
+
+### When to pick which
+
+| Scenario | Executor | Why |
+| --- | --- | --- |
+| Local script, CLI, single-process server | `LocalExecutor` | No infra needed; awaitable end-to-end. |
+| HTTP server returning the final answer in one response | `LocalExecutor` | The request handler awaits the whole loop. |
+| HTTP server returning `runId` immediately, client polls | either | Use `Local` with a background worker, or `Lambda` for serverless. |
+| Long-running agent runs (many tool calls, big chains) | `LambdaExecutor` | Each iteration fits inside one invocation — no 15-min Lambda cap risk. |
+| Bursty workloads, scale-to-zero | `LambdaExecutor` | Pay only for active iterations; no idle worker. |
+| Same code in dev and prod | both | Swap the executor at construction time; everything else stays identical. |
+
+### Custom executors
+
+Anything that implements `scheduleNextIteration(runId)` works. Useful scenarios:
+
+- **Queue-backed worker** — push `{ runId, action: "continue" }` to SQS / Redis / Cloud Tasks; a separate worker pool dequeues and calls `continueRun(runId)`. Buys you backpressure and retries the framework doesn't give you natively.
+- **Cron / scheduled continuation** — schedule the next tick instead of firing it immediately (e.g. to throttle, or wait on an external event).
+- **Cross-region failover** — invoke a Lambda in a different region when the primary is degraded.
+
+Skeleton:
+
+```ts
+import { Executor, PromptHandler } from "thoughtgear";
+
+class SqsExecutor implements Executor {
+  constructor(private queueUrl: string, private sqs: SQSClient) {}
+  async scheduleNextIteration(runId: string) {
+    await this.sqs.send(new SendMessageCommand({
+      QueueUrl: this.queueUrl,
+      MessageBody: JSON.stringify({ runId, action: "continue" }),
+    }));
+  }
+}
+```
+
+Your worker then reads the queue and calls `handler.continueRun(runId)` per message.
+
 ## Switching providers
 
 Just change `model.provider`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thoughtgear",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Minimal agent loop: send a prompt, the model can call tools, and the loop persists transcript + state until the model is done.",
   "type": "module",
   "main": "./dist/index.js",