@theokit/cli 3.0.2 → 4.0.1

package/templates/telegram-bot/src/index.ts

@@ -7,7 +7,7 @@
 
 import { GatewayRunner } from "@theokit/gateway";
 import { TelegramAdapter } from "@theokit/gateway-telegram";
-import { createAgentFactory } from "@theokit/sdk";
+import { AgentFactory } from "@theokit/sdk";
 import { Bot } from "grammy";
 
 const TELEGRAM_BOT_TOKEN = process.env.TELEGRAM_BOT_TOKEN;
@@ -21,7 +21,7 @@ if (TELEGRAM_BOT_TOKEN === undefined || TELEGRAM_BOT_TOKEN.length === 0) {
 const API_KEY = process.env.THEOKIT_API_KEY ?? "local";
 const MODEL = process.env.AGENT_MODEL ?? "anthropic/claude-3-5-sonnet-latest";
 
-const factory = createAgentFactory({
+const factory = AgentFactory.create({
   apiKey: API_KEY,
   model: { id: MODEL },
   local: { cwd: process.cwd() },

package/templates/workflow-automation/.env.example

@@ -0,0 +1,14 @@
+# Copy to .env and fill in:
+#
+# THEOKIT_API_KEY — any non-empty string. Used by the SDK for cloud
+# catalog reads; not strictly required for chat against Anthropic/OpenAI
+# directly. Set to "local" if you're not using Theo cloud.
+THEOKIT_API_KEY=local
+
+# Provider key — pick ONE. The SDK auto-detects which one is set.
+# ANTHROPIC_API_KEY=sk-ant-...
+# OPENAI_API_KEY=sk-...
+# OPENROUTER_API_KEY=sk-or-...
+
+# Override the model (default: anthropic/claude-3-5-sonnet-latest).
+# AGENT_MODEL=openai/gpt-4o-mini

package/templates/workflow-automation/README.md

@@ -0,0 +1,33 @@
+# {{projectName}}
+
+A scheduled, multi-step pipeline, scaffolded by `theokit init`.
+
+## Setup
+
+```bash
+pnpm install
+cp .env.example .env
+pnpm dev
+```
+
+## What this does
+
+1. `Workflow.create(…).then(…).commit()` builds a three-step pipeline:
+   `fn("collect")` → `agentStep("analyse")` → `fn("format")`.
+2. Runs it once so you can see the output.
+3. Hands the SAME committed workflow to `Cron.create({ cron, workflow })`.
+
+The workflow is the unit of work; cron only decides when. `agentStep` runs the
+agent and feeds it the previous step's output — there is no stream to drain by
+hand, which is the difference between this and calling `agent.send` in a loop.
+
+## Requirements
+
+- Node 22.12+.
+- One of: Anthropic / OpenAI / OpenRouter API key.
+
+## Next steps
+
+- `WORKFLOW_CRON="@hourly"` — five-field POSIX cron or a shorthand.
+- Replace `fn("collect")` with a real fetch; the other two steps do not change.
+- `.parallel(…)`, `.branch(…)`, `.foreach(…)` for fan-out and conditionals.

package/templates/workflow-automation/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx --env-file=.env src/index.ts",
+    "start": "tsx --env-file=.env src/index.ts"
+  },
+  "dependencies": {
+    "@theokit/sdk": "^{{sdkVersion}}"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.0"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  }
+}

package/templates/workflow-automation/src/index.ts

@@ -0,0 +1,86 @@
+/**
+ * {{projectName}} — a scheduled, multi-step pipeline.
+ *
+ * Builds a real `Workflow` (fetch -> analyse -> format), runs it once so you can
+ * see the output, then hands the SAME committed workflow to `Cron` to run on a
+ * schedule. The workflow is the unit of work; cron only decides when.
+ */
+
+import { Agent, agentStep, Cron, fn, Workflow } from "@theokit/sdk";
+
+const API_KEY = process.env.THEOKIT_API_KEY ?? "local";
+const MODEL = process.env.AGENT_MODEL ?? "anthropic/claude-3-5-sonnet-latest";
+/** Five-field POSIX cron, or a shorthand like `@hourly`. */
+const SCHEDULE = process.env.WORKFLOW_CRON ?? "*/5 * * * *";
+
+async function main(): Promise<void> {
+  const analyst = await Agent.create({
+    agentId: "workflow-analyst",
+    apiKey: API_KEY,
+    model: { id: MODEL },
+    systemPrompt:
+      "You read a system health snapshot and reply with three bullet points: " +
+      "what is fine, what to watch, and what to act on now. No preamble.",
+    local: { cwd: process.cwd() },
+  });
+
+  try {
+    const pipeline = Workflow.create({ name: "health-report" })
+      // Step 1 — plain function. In production this reads an API or a database.
+      .then(
+        fn("collect", () => {
+          const at = new Date().toISOString();
+          return `[${at}] CPU 45% · Memory 72% · Requests 1.2k/s · Errors 0.3%`;
+        }),
+      )
+      // Step 2 — an agent step. The SDK runs the agent and feeds it the previous
+      // step's output; there is no stream to drain by hand.
+      .then(
+        agentStep("analyse", analyst, (snapshot) => `Analyse this snapshot:\n${String(snapshot)}`),
+      )
+      // Step 3 — shape the result. Keeping formatting OUT of the agent step is
+      // what lets you change the report without touching the prompt.
+      .then(fn("format", (report) => `--- health report ---\n${String(report)}\n---`))
+      .commit();
+
+    console.log("Running the pipeline once...\n");
+    const run = await pipeline.run({});
+    if (run.status === "completed") {
+      console.log(String(run.output));
+    } else {
+      console.error(`pipeline ${run.status}`);
+      process.exitCode = 1;
+    }
+
+    // Same committed workflow, now on a schedule. The field is `cron` — and a
+    // workflow target takes no `message`, because the workflow IS the work.
+    const job = await Cron.create({
+      name: "health-report",
+      cron: SCHEDULE,
+      workflow: pipeline,
+      apiKey: API_KEY,
+    });
+    console.log(`\nScheduled ${job.name ?? job.id} at "${job.cron}" (${job.timezone ?? "UTC"}).`);
+
+    await Cron.start({ apiKey: API_KEY });
+    console.log("Scheduler running. Ctrl+C to stop.");
+
+    // Wire shutdown ONCE, and await the stop: exiting while the scheduler still
+    // holds timers is what leaves a half-run behind.
+    process.on("SIGINT", () => {
+      void (async () => {
+        await Cron.stop();
+        await analyst.dispose();
+        process.exit(0);
+      })();
+    });
+  } catch (cause) {
+    await analyst.dispose();
+    throw cause;
+  }
+}
+
+main().catch((cause) => {
+  console.error("workflow failed:", cause instanceof Error ? cause.message : cause);
+  process.exit(1);
+});

package/templates/workflow-automation/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "lib": ["ES2023", "ESNext.Disposable"]
+  },
+  "include": ["src/**/*.ts"]
+}