create-theokit 1.25.2 → 2.0.0-next.0

package/templates/default/src/server/agents/hooks/tool-audit.ts

@@ -0,0 +1,75 @@
+import type { HookHandlers } from '@theokit/agents'
+
+/**
+ * Lifecycle hooks — the seam where you observe or intercept the agent loop.
+ *
+ * A tool call is the moment your agent stops talking and starts *doing*: it hits the network, writes
+ * a row, sends a message. This hook makes every one of those visible, with the timing, so a slow or
+ * looping agent is something you can see in a log rather than something you infer from a user
+ * complaint.
+ *
+ * Eight events exist. These two are the pair you almost always want first:
+ *
+ * | Event | When | Can it stop the call? |
+ * |---|---|---|
+ * | `pre_tool_call` | before the tool runs | **yes** — return `{ block: true, message }` |
+ * | `post_tool_call` | after it returns | no — fire-and-forget |
+ * | `transform_tool_result` | folds the turn's results before the model sees them | rewrites |
+ * | `transform_llm_output` | folds the model's text | rewrites |
+ * | `on_session_start` / `on_session_end` | session lifecycle | no |
+ * | `pre_user_send` / `post_assistant_reply` | around a user turn | no |
+ *
+ * ## Why this one only observes
+ *
+ * `pre_tool_call` is the only hook with veto power, and it is tempting to ship a template that uses
+ * it. It is deliberately not used here: a veto encodes a policy, and any policy this file could
+ * invent would be one your app did not ask for. `send_notification` is already gated the right way
+ * — by a human approval in `chat.ts` — which is where a decision belongs when a person should make
+ * it. Reach for the veto when you have a rule of your own:
+ *
+ * ```ts
+ * pre_tool_call: (ctx) =>
+ *   ctx.name === 'delete_account' && !isAdmin(ctx)
+ *     ? { block: true, message: 'Only an admin may delete an account.' }
+ *     : undefined,
+ * ```
+ *
+ * The message goes to the MODEL, not the user — write it as an instruction the agent can act on.
+ */
+
+/** Start times by `${runId}:${name}`, so a duration survives concurrent calls in one run. */
+const started = new Map<string, number>()
+
+function key(runId: string, name: string): string {
+  return `${runId}:${name}`
+}
+
+export const toolAuditHooks: HookHandlers = {
+  pre_tool_call: (ctx) => {
+    started.set(key(ctx.runId, ctx.name), Date.now())
+    // One structured line per call. Structured, not a sentence, because the thing you will want
+    // later is a filter (`tool=weather`), and a sentence has to be parsed back apart to give you one.
+    console.info(
+      JSON.stringify({ event: 'tool.start', tool: ctx.name, runId: ctx.runId, args: ctx.args }),
+    )
+    // `undefined` lets the call through. Returning nothing is not the same as approving nothing:
+    // this hook makes no decision, and that is the point of the docblock above.
+    return undefined
+  },
+
+  post_tool_call: (ctx) => {
+    const k = key(ctx.runId, ctx.name)
+    const startedAt = started.get(k)
+    started.delete(k)
+    console.info(
+      JSON.stringify({
+        event: 'tool.end',
+        tool: ctx.name,
+        runId: ctx.runId,
+        // Absent rather than zero when the start was never seen — a duration of 0ms would read as
+        // an instant call instead of as a missing measurement.
+        ms: startedAt === undefined ? undefined : Date.now() - startedAt,
+      }),
+    )
+  },
+}

package/templates/default/theo.config.ts

@@ -1,3 +1,20 @@
 import { config } from 'theokit'
 
-export default config().build()
+/**
+ * The project has two surfaces, and one of them is the whole backend.
+ *
+ * `src/app` is the interface. `src/server` is everything that only runs on the server — and agents
+ * are part of that, not a third surface beside it. An agent shares this project's context, auth,
+ * services and infrastructure with every controller and route; a layout that puts `agents/` beside
+ * `server/` suggests two backends and invites both to grow their own copy of all four.
+ *
+ * The paths are declared rather than inherited. The defaults are still the flat layout
+ * (`app`, `server`, `agents`), so a project that says nothing keeps working exactly as before —
+ * writing them down is what lets this scaffold move without waiting for a major, and what stops a
+ * future default change from silently relocating anyone's code.
+ */
+export default config()
+  .appDir('src/app')
+  .serverDir('src/server')
+  .agentsDir('src/server/agents')
+  .build()

package/templates/default/tsconfig.json

@@ -14,11 +14,10 @@
     "emitDecoratorMetadata": true
   },
   "include": [
-    "app/**/*.ts",
-    "app/**/*.tsx",
-    "server/**/*.ts",
-    "agents/**/*.ts",
-    "shared/**/*.ts",
+    "src/app/**/*.ts",
+    "src/app/**/*.tsx",
+    "src/server/**/*.ts",
+    "src/shared/**/*.ts",
     ".theokit/**/*.d.ts",
     "types/**/*.d.ts"
   ]