@tdk-landscape/tdk-cli-core 1.3.170 → 1.3.172

package/README.md

@@ -28,6 +28,19 @@ No vendor lock-in. No tedious plumbing. Run a single command to natively orchest
 * **Databases & Tooling:** Prisma, Drizzle, Atlas, Dbmate
 * **Messaging & Gateway:** NATS, Traefik
 
+### 🤖 Run your AI agents next to your services
+
+TDK is the local runtime for agent *systems*: the agent, its MCP tools, its database, its queue, behind one gateway, one command.
+
+```bash
+# Scaffold an agent, an MCP tools server, and a database in one stack
+tdk resource bot --type agent --stack shop --yes
+tdk resource tools-mcp --type mcp --stack shop --yes
+tdk up shop
+```
+
+Agents get durable checkpoint volumes that survive `tdk down`, sticky session routing via `x-session-id`, graceful SIGTERM drain during hot reloads, a Docker health check on `/health`, and application-level readiness checks on `/ready`. See the [AI agents guide](docs/agents/ai-agents.md) and [honest comparison with agent frameworks](docs/compare-honest.md#ai-agent-frameworks-and-workflow-engines-libfx-langgraph-mastra-vercel-workflows-temporal).
+
 
 TDK CLI — start services on your machine. It is not a deploy and not a Compose file: define each service in `service.json`, then run `tdk up`. No Kubernetes is needed on the machine.
 
@@ -128,6 +141,7 @@ Set `TDK_DEBUG=1` before running `tdk up --verbose` to include Starlark debug lo
 - [Mega cheat sheet: every command and flag](docs/cheat-sheet.md)
 - [Documentation index](docs/README.md)
 - [Pilot TDK on a real repository](docs/adopt-tdk.md)
+- [Running AI agents in TDK](docs/agents/ai-agents.md)
 - [FAQ for agencies and multi-client teams](docs/faq-teams.md)
 - [Working alongside Helm](docs/with-helm.md)
 - [Scope: local development, and what does not carry over to production](docs/scope.md)

package/cli/dist/agent-runtimes/custom.js

@@ -0,0 +1,333 @@
+/**
+ * The `custom` agent runtime: a plain Bun HTTP service with no model SDK, no agent framework and no vendor dependency.
+ * It is the escape hatch the agent resource type is built on. Replace the `runTurn` body with your model call and tools;
+ * the process contract around it (health, readiness, session checkpoints, SIGTERM drain) is what TDK relies on.
+ */
+export function getCustomAgentIndexTemplate(name, durability = "files") {
+    if (durability === "postgres") {
+        return `import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
+import { Client } from 'pg';
+
+// Contract with TDK (see docs/agents/ai-agents.md):
+//   AGENT_DURABILITY  postgres
+//   DATABASE_URL      Postgres connection string injected by TDK
+//   PORT              port to listen on
+// /health: the process is alive. /ready: the checkpoint store is reachable. Idle is healthy, so /health never checks the store.
+
+const DURABILITY = 'postgres';
+const PORT = Number(process.env.PORT || 3000);
+const DRAIN_TIMEOUT_MS = 10_000;
+const DATABASE_URL = process.env.DATABASE_URL || 'postgresql://postgres:postgres@localhost:5432/postgres';
+
+interface Checkpoint {
+  sessionId: string;
+  messages: Array<{ role: 'user' | 'agent'; content: string; at: string }>;
+}
+
+let client: Client | null = null;
+let initialized = false;
+
+async function getClient(): Promise<Client> {
+  if (client) return client;
+  const c = new Client({ connectionString: DATABASE_URL });
+  await c.connect();
+  if (!initialized) {
+    await c.query(\`
+      CREATE TABLE IF NOT EXISTS tdk_agent_sessions (
+        session_id VARCHAR(128) PRIMARY KEY,
+        messages JSONB NOT NULL DEFAULT '[]'::jsonb,
+        updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      );
+    \`);
+    initialized = true;
+  }
+  client = c;
+  return client;
+}
+
+const store = {
+  async ready(): Promise<boolean> {
+    try {
+      const c = await getClient();
+      await c.query('SELECT 1');
+      return true;
+    } catch {
+      client = null;
+      return false;
+    }
+  },
+  async load(sessionId: string): Promise<Checkpoint> {
+    try {
+      const c = await getClient();
+      const res = await c.query('SELECT messages FROM tdk_agent_sessions WHERE session_id = $1', [sessionId]);
+      if (res.rows.length > 0 && res.rows[0].messages) {
+        return { sessionId, messages: res.rows[0].messages };
+      }
+      return { sessionId, messages: [] };
+    } catch (err) {
+      console.error('[agent] load checkpoint failed:', err);
+      return { sessionId, messages: [] };
+    }
+  },
+  async save(checkpoint: Checkpoint): Promise<void> {
+    const c = await getClient();
+    await c.query(
+      \`INSERT INTO tdk_agent_sessions (session_id, messages, updated_at)
+       VALUES ($1, $2, NOW())
+       ON CONFLICT (session_id) DO UPDATE
+       SET messages = EXCLUDED.messages, updated_at = NOW()\`,
+      [checkpoint.sessionId, JSON.stringify(checkpoint.messages)],
+    );
+  },
+  async close(): Promise<void> {
+    if (client) {
+      try {
+        await client.end();
+      } catch {}
+      client = null;
+    }
+  },
+};
+
+// Replace this with the agent's work: call your model, run tools, return the reply. Keep it a pure function of the
+// checkpoint so a resumed session continues from what was saved.
+async function runTurn(checkpoint: Checkpoint, input: string): Promise<string> {
+  // The caller has already appended this turn's user message, so the turn number is half the message count, rounded up.
+  return 'received ' + input + ' (turn ' + Math.ceil(checkpoint.messages.length / 2) + ')';
+}
+
+let draining = false;
+let inFlight = 0;
+
+function sendJson(res: ServerResponse, status: number, body: unknown) {
+  res.statusCode = status;
+  res.setHeader('content-type', 'application/json');
+  res.end(JSON.stringify(body));
+}
+
+async function readJson(req: IncomingMessage): Promise<any> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) chunks.push(chunk as Buffer);
+  const raw = Buffer.concat(chunks).toString('utf8');
+  return raw ? JSON.parse(raw) : {};
+}
+
+const server = createServer(async (req, res) => {
+  inFlight++;
+  res.on('close', () => inFlight--);
+  const url = new URL(req.url ?? '/', 'http://localhost');
+
+  try {
+    if (url.pathname === '/health') {
+      return sendJson(res, 200, { status: 'ok', service: '${name}', draining });
+    }
+
+    if (url.pathname === '/ready') {
+      const ok = !draining && (await store.ready());
+      return sendJson(res, ok ? 200 : 503, { ready: ok, durability: DURABILITY });
+    }
+
+    // Session routing: the session id comes from the x-session-id header, so several instances of one agent can
+    // share a Traefik route and each session still reaches its own checkpoint.
+    if (url.pathname === '/turn' && req.method === 'POST') {
+      if (draining) return sendJson(res, 503, { error: 'draining' });
+      const sessionId = String(req.headers['x-session-id'] ?? '');
+      if (!/^[A-Za-z0-9_-]{1,128}$/.test(sessionId)) {
+        return sendJson(res, 400, { error: 'x-session-id header is required (1-128 letters, digits, - or _)' });
+      }
+      const body = await readJson(req);
+      const input = String(body.input ?? '');
+      const checkpoint = await store.load(sessionId);
+      checkpoint.messages.push({ role: 'user', content: input, at: new Date().toISOString() });
+      const reply = await runTurn(checkpoint, input);
+      checkpoint.messages.push({ role: 'agent', content: reply, at: new Date().toISOString() });
+      await store.save(checkpoint);
+      return sendJson(res, 200, { sessionId, reply, turns: checkpoint.messages.length / 2 });
+    }
+
+    if (url.pathname === '/session' && req.method === 'GET') {
+      const sessionId = String(req.headers['x-session-id'] ?? '');
+      if (!/^[A-Za-z0-9_-]{1,128}$/.test(sessionId)) return sendJson(res, 400, { error: 'x-session-id header is required' });
+      const checkpoint = await store.load(sessionId);
+      return sendJson(res, 200, { sessionId, turns: checkpoint.messages.length / 2, messages: checkpoint.messages });
+    }
+
+    return sendJson(res, 404, { error: 'not_found' });
+  } catch (error) {
+    console.error('[agent] request failed:', error);
+    return sendJson(res, 500, { error: 'internal_error' });
+  }
+});
+
+// Bind beyond loopback: Traefik reaches the container over the Docker network.
+server.listen(PORT, '0.0.0.0', () => {
+  console.log('\\n🤖 ${name} agent on http://localhost:' + PORT + ' (durability: ' + DURABILITY + ')');
+});
+
+// Drain on SIGTERM (tdk down, hot reload, docker stop): stop taking turns, let in-flight turns finish, then exit 0.
+// Checkpoints are written before a turn is answered, so a drained exit loses no acknowledged turn.
+function shutdown(signal: string) {
+  if (draining) return;
+  draining = true;
+  console.log('[agent] ' + signal + ' received, draining ' + inFlight + ' in-flight request(s)');
+  server.close(async () => {
+    await store.close();
+  });
+  const deadline = Date.now() + DRAIN_TIMEOUT_MS;
+  const timer = setInterval(async () => {
+    if (inFlight === 0 || Date.now() > deadline) {
+      clearInterval(timer);
+      await store.close();
+      process.exit(0);
+    }
+  }, 100);
+}
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));
+`;
+    }
+    return `import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
+import { mkdirSync, readFileSync, renameSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+// Contract with TDK (see docs/agents/ai-agents.md):
+//   AGENT_DURABILITY  files   (set by tdk from service.json agent.durability)
+//   AGENT_STATE_DIR   where files-durability checkpoints live (a named volume that survives tdk down)
+//   PORT              port to listen on
+// /health: the process is alive. /ready: the checkpoint store is reachable. Idle is healthy, so /health never checks the store.
+
+const DURABILITY = 'files';
+const STATE_DIR = process.env.AGENT_STATE_DIR || join(process.cwd(), '.agent-state');
+const PORT = Number(process.env.PORT || 3000);
+const DRAIN_TIMEOUT_MS = 10_000;
+
+interface Checkpoint {
+  sessionId: string;
+  messages: Array<{ role: 'user' | 'agent'; content: string; at: string }>;
+}
+
+// Session store. files: one JSON checkpoint per session, written atomically (temp file, then rename), so a kill
+// mid-write leaves the previous checkpoint intact.
+const store = {
+  ready(): boolean {
+    try {
+      mkdirSync(STATE_DIR, { recursive: true });
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  load(sessionId: string): Checkpoint {
+    const file = join(STATE_DIR, sessionId + '.json');
+    return existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : { sessionId, messages: [] };
+  },
+  save(checkpoint: Checkpoint): void {
+    mkdirSync(STATE_DIR, { recursive: true });
+    const file = join(STATE_DIR, checkpoint.sessionId + '.json');
+    const tmp = file + '.' + process.pid + '.tmp';
+    writeFileSync(tmp, JSON.stringify(checkpoint));
+    renameSync(tmp, file);
+  },
+};
+
+// Replace this with the agent's work: call your model, run tools, return the reply. Keep it a pure function of the
+// checkpoint so a resumed session continues from what was saved.
+async function runTurn(checkpoint: Checkpoint, input: string): Promise<string> {
+  // The caller has already appended this turn's user message, so the turn number is half the message count, rounded up.
+  return 'received ' + input + ' (turn ' + Math.ceil(checkpoint.messages.length / 2) + ')';
+}
+
+let draining = false;
+let inFlight = 0;
+
+function sendJson(res: ServerResponse, status: number, body: unknown) {
+  res.statusCode = status;
+  res.setHeader('content-type', 'application/json');
+  res.end(JSON.stringify(body));
+}
+
+async function readJson(req: IncomingMessage): Promise<any> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) chunks.push(chunk as Buffer);
+  const raw = Buffer.concat(chunks).toString('utf8');
+  return raw ? JSON.parse(raw) : {};
+}
+
+const server = createServer(async (req, res) => {
+  inFlight++;
+  res.on('close', () => inFlight--);
+  const url = new URL(req.url ?? '/', 'http://localhost');
+
+  try {
+    if (url.pathname === '/health') {
+      return sendJson(res, 200, { status: 'ok', service: '${name}', draining });
+    }
+
+    if (url.pathname === '/ready') {
+      const ok = !draining && (await store.ready());
+      return sendJson(res, ok ? 200 : 503, { ready: ok, durability: DURABILITY });
+    }
+
+    // Session routing: the session id comes from the x-session-id header, so several instances of one agent can
+    // share a Traefik route and each session still reaches its own checkpoint.
+    if (url.pathname === '/turn' && req.method === 'POST') {
+      if (draining) return sendJson(res, 503, { error: 'draining' });
+      const sessionId = String(req.headers['x-session-id'] ?? '');
+      if (!/^[A-Za-z0-9_-]{1,128}$/.test(sessionId)) {
+        return sendJson(res, 400, { error: 'x-session-id header is required (1-128 letters, digits, - or _)' });
+      }
+      const body = await readJson(req);
+      const input = String(body.input ?? '');
+      const checkpoint = await store.load(sessionId);
+      checkpoint.messages.push({ role: 'user', content: input, at: new Date().toISOString() });
+      const reply = await runTurn(checkpoint, input);
+      checkpoint.messages.push({ role: 'agent', content: reply, at: new Date().toISOString() });
+      await store.save(checkpoint);
+      return sendJson(res, 200, { sessionId, reply, turns: checkpoint.messages.length / 2 });
+    }
+
+    if (url.pathname === '/session' && req.method === 'GET') {
+      const sessionId = String(req.headers['x-session-id'] ?? '');
+      if (!/^[A-Za-z0-9_-]{1,128}$/.test(sessionId)) return sendJson(res, 400, { error: 'x-session-id header is required' });
+      const checkpoint = await store.load(sessionId);
+      return sendJson(res, 200, { sessionId, turns: checkpoint.messages.length / 2, messages: checkpoint.messages });
+    }
+
+    return sendJson(res, 404, { error: 'not_found' });
+  } catch (error) {
+    console.error('[agent] request failed:', error);
+    return sendJson(res, 500, { error: 'internal_error' });
+  }
+});
+
+// Bind beyond loopback: Traefik reaches the container over the Docker network.
+server.listen(PORT, '0.0.0.0', () => {
+  console.log('\\n🤖 ${name} agent on http://localhost:' + PORT + ' (durability: ' + DURABILITY + ')');
+});
+
+// Drain on SIGTERM (tdk down, hot reload, docker stop): stop taking turns, let in-flight turns finish, then exit 0.
+// Checkpoints are written before a turn is answered, so a drained exit loses no acknowledged turn.
+function shutdown(signal: string) {
+  if (draining) return;
+  draining = true;
+  console.log('[agent] ' + signal + ' received, draining ' + inFlight + ' in-flight request(s)');
+  server.close();
+  const deadline = Date.now() + DRAIN_TIMEOUT_MS;
+  const timer = setInterval(() => {
+    if (inFlight === 0 || Date.now() > deadline) {
+      clearInterval(timer);
+      process.exit(0);
+    }
+  }, 100);
+}
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));
+`;
+}
+export const customAgentRuntime = {
+    id: "custom",
+    label: "Custom agent runtime (Bun HTTP, no vendor dependency)",
+    dependencies: {},
+    devDependencies: {},
+    createIndex: getCustomAgentIndexTemplate,
+};

package/cli/dist/agent-runtimes/registry.js

@@ -0,0 +1,34 @@
+// Copyright (c) 2026 TDK Landscape contributors
+// SPDX-License-Identifier: MIT
+import { TdkError } from "../utils/errors.js";
+import { customAgentRuntime } from "./custom.js";
+/**
+ * Agent runtimes an `agent` resource can be scaffolded with. No runtime is privileged: each is a scaffold plus the
+ * process contract in its index file, and `custom` is the default because it has no vendor dependency.
+ */
+export const AGENT_RUNTIMES = {
+    custom: customAgentRuntime,
+};
+export const DEFAULT_AGENT_RUNTIME = "custom";
+export const AGENT_DURABILITY_OPTIONS = ["files", "postgres"];
+export function resolveAgentRuntime(runtimeId) {
+    const id = runtimeId ?? DEFAULT_AGENT_RUNTIME;
+    const provider = AGENT_RUNTIMES[id];
+    if (!provider) {
+        const supported = Object.keys(AGENT_RUNTIMES).join(", ");
+        throw new TdkError(`Unknown agent runtime "${id}". Supported runtimes: ${supported}.`, [
+            `Use one of: ${supported}`,
+            `Omit --runtime to use ${DEFAULT_AGENT_RUNTIME}`,
+        ]);
+    }
+    return provider;
+}
+export function resolveAgentDurability(value) {
+    const durability = value ?? "files";
+    if (!AGENT_DURABILITY_OPTIONS.includes(durability)) {
+        throw new TdkError(`Unknown --durability "${durability}".`, [
+            `Use one of: ${AGENT_DURABILITY_OPTIONS.join(", ")}`,
+        ]);
+    }
+    return durability;
+}

package/cli/dist/backend-frameworks/registry.js

@@ -1,5 +1,6 @@
 // Copyright (c) 2026 TDK Landscape contributors
 // SPDX-License-Identifier: MIT
+import { resolveAgentRuntime } from "../agent-runtimes/registry.js";
 import { getBackendIndexTemplate } from "../backend-languages/bun.js";
 import { TdkError } from "../utils/errors.js";
 import { elysiaBackendProvider } from "./elysia.js";
@@ -56,6 +57,21 @@ export function resolveBackendFramework(resourceType, frameworkId, language) {
         }
         return mcpBackendProvider;
     }
+    // `agent` is scaffolded by an agent runtime (src/agent-runtimes/), not a framework. Only the default runtime is reachable here:
+    // `tdk resource` validates --runtime before it scaffolds, so the package.json and tsconfig always match the chosen runtime.
+    if (resourceType === "agent") {
+        if (frameworkId !== undefined && frameworkId !== "custom") {
+            throw new TdkError("--framework cannot be combined with --type agent.", [
+                "An agent resource is scaffolded by an agent runtime; use --runtime <id> instead",
+            ]);
+        }
+        if (language?.createFiles) {
+            throw new TdkError(`--language ${language.id} cannot be combined with --type agent.`, [
+                "An agent resource is a Bun service; drop --language",
+            ]);
+        }
+        return resolveAgentRuntime();
+    }
     if (resourceType !== "backend" || frameworkId === undefined)
         return undefined;
     if (language?.createFiles) {

package/cli/dist/cli.js

@@ -4,6 +4,7 @@
 import chalk from "chalk";
 import { Command } from "commander";
 import pkg from "../package.json" with { type: "json" };
+import { agentCommand } from "./commands/agent.js";
 import { completionCommand } from "./commands/completion.js";
 import { configCommand } from "./commands/config.js";
 import { doctorCommand } from "./commands/doctor.js";
@@ -19,6 +20,7 @@ import { projectCommand } from "./commands/project.js";
 import { projectsCommand } from "./commands/projects.js";
 import { resourceCommand } from "./commands/resource.js";
 import { resourcesCommand } from "./commands/resources.js";
+import { restartCommand } from "./commands/restart.js";
 import { runtimeCommand } from "./commands/runtime.js";
 import { stackCommand } from "./commands/stack.js";
 import { stacksCommand } from "./commands/stacks.js";
@@ -67,6 +69,8 @@ program.addCommand(doctorCommand);
 program.addCommand(completionCommand);
 program.addCommand(upgradeCommand);
 program.addCommand(networksCommand);
+program.addCommand(agentCommand);
+program.addCommand(restartCommand);
 // Default: show help if no command provided
 if (process.argv.length === 2) {
     const result = await runColdPreflight();

package/cli/dist/commands/agent.js

@@ -0,0 +1,117 @@
+// Copyright (c) 2026 TDK Landscape contributors
+// SPDX-License-Identifier: MIT
+import chalk from "chalk";
+import { Command } from "commander";
+import { createDiscoveryContext } from "../utils/discovery-context.js";
+import { errorFactories, runCommand, TdkError } from "../utils/errors.js";
+import { createMachineEnvelope, writeMachineError } from "../utils/machine-output.js";
+import { findProjectRoot } from "../utils/paths.js";
+const SESSION_REQUEST_TIMEOUT_MS = 10_000;
+export const agentCommand = new Command("agent").description("Inspect and operate AI agent resources");
+agentCommand
+    .command("sessions <resource>")
+    .description("Inspect session checkpoints from a running AI agent resource")
+    .option("--session-id <id>", "Specific session ID to fetch")
+    .option("--json", "Output one JSON object and exit", false)
+    .action(async (resourceName, options) => {
+    const action = async () => {
+        const root = findProjectRoot();
+        if (!root) {
+            const error = errorFactories.notInProject();
+            if (options.json)
+                writeMachineError(error);
+            error.exit();
+        }
+        const discovery = createDiscoveryContext();
+        const resource = discovery.resources.find((r) => r.name === resourceName);
+        if (!resource) {
+            const msg = `Resource "${resourceName}" not found in project.`;
+            if (options.json) {
+                console.log(JSON.stringify(createMachineEnvelope(null, [{ code: "UNKNOWN_RESOURCE", message: msg }])));
+                process.exit(1);
+            }
+            throw new TdkError(msg);
+        }
+        const appType = resource.config?.appType ?? resource.type;
+        if (appType !== "agent") {
+            const msg = `Resource "${resourceName}" is of type "${appType}", not "agent".`;
+            if (options.json) {
+                console.log(JSON.stringify(createMachineEnvelope(null, [{ code: "NOT_AN_AGENT", message: msg }])));
+                process.exit(1);
+            }
+            throw new TdkError(msg);
+        }
+        const port = resource.port;
+        if (!port) {
+            const msg = `Agent "${resourceName}" has no assigned port.`;
+            if (options.json) {
+                console.log(JSON.stringify(createMachineEnvelope(null, [{ code: "NO_PORT", message: msg }])));
+                process.exit(1);
+            }
+            throw new TdkError(msg);
+        }
+        const headers = {};
+        if (options.sessionId) {
+            headers["x-session-id"] = String(options.sessionId);
+        }
+        let res;
+        let bodyText;
+        try {
+            // One signal covers both the connection and the body read, so a hung agent cannot block the CLI.
+            res = await fetch(`http://127.0.0.1:${port}/session`, {
+                method: "GET",
+                headers,
+                signal: AbortSignal.timeout(SESSION_REQUEST_TIMEOUT_MS),
+            });
+            bodyText = await res.text();
+        }
+        catch {
+            const msg = `Agent "${resourceName}" is not responding on port ${port}. Is the stack running?`;
+            if (options.json) {
+                console.log(JSON.stringify(createMachineEnvelope(null, [{ code: "AGENT_NOT_RUNNING", message: msg }])));
+                process.exit(1);
+            }
+            throw new TdkError(msg, ["Start the stack with: tdk up"]);
+        }
+        let body = {};
+        try {
+            body = bodyText ? JSON.parse(bodyText) : {};
+        }
+        catch {
+            body = { raw: bodyText };
+        }
+        if (!res.ok) {
+            const detail = body?.error ?? bodyText;
+            if (options.json) {
+                console.log(JSON.stringify(createMachineEnvelope(null, [
+                    {
+                        code: "AGENT_REQUEST_FAILED",
+                        message: `Agent returned ${res.status}: ${detail}`,
+                    },
+                ])));
+                process.exit(1);
+            }
+            throw new TdkError(`Agent error (${res.status}): ${detail}`);
+        }
+        if (options.json) {
+            console.log(JSON.stringify(createMachineEnvelope({
+                agent: resourceName,
+                port,
+                session: body,
+            })));
+            return;
+        }
+        console.log(chalk.bold(`Sessions for ${resourceName}:`));
+        console.log(JSON.stringify(body, null, 2));
+    };
+    if (options.json) {
+        try {
+            await action();
+        }
+        catch (err) {
+            writeMachineError(err);
+        }
+        return;
+    }
+    await runCommand(action);
+});

package/cli/dist/commands/completion.js

@@ -13,7 +13,7 @@ _tdk_completions() {
     prev="\${COMP_WORDS[COMP_CWORD-1]}"
     
     # Main commands
-    local commands="project projects stack stacks resource resources up down status ui doctor runtime version completion help upgrade mcp logs eject import config maintainers networks traefik"
+    local commands="project projects stack stacks resource resources agent restart up down status ui doctor runtime version completion help upgrade mcp logs eject import config maintainers networks traefik"
     
     # Options for specific commands
     case "\${prev}" in
@@ -136,6 +136,8 @@ _tdk_commands() {
         'stacks:List all stacks'
         'resource:Create new resource'
         'resources:List all resources'
+        'agent:Inspect and operate AI agent resources'
+        'restart:Restart a running resource in the stack'
         'up:Start services'
         'down:Stop all services'
         'status:Show resource status'
@@ -189,6 +191,8 @@ complete -c tdk -n '__fish_use_subcommand' -a 'stack' -d 'Organize resources int
 complete -c tdk -n '__fish_use_subcommand' -a 'stacks' -d 'List all stacks'
 complete -c tdk -n '__fish_use_subcommand' -a 'resource' -d 'Create new resource'
 complete -c tdk -n '__fish_use_subcommand' -a 'resources' -d 'List all resources'
+complete -c tdk -n '__fish_use_subcommand' -a 'agent' -d 'Inspect and operate AI agent resources'
+complete -c tdk -n '__fish_use_subcommand' -a 'restart' -d 'Restart a running resource in the stack'
 complete -c tdk -n '__fish_use_subcommand' -a 'up' -d 'Start services'
 complete -c tdk -n '__fish_use_subcommand' -a 'down' -d 'Stop all services'
 complete -c tdk -n '__fish_use_subcommand' -a 'status' -d 'Show resource status'

package/cli/dist/commands/help.js

@@ -42,6 +42,11 @@ const COMMAND_GROUPS = [
         commands: [
             { name: "resource", desc: "Create new resource with templates", alias: "" },
             { name: "resources", desc: "List all resources with filtering", alias: "--stack, --ports" },
+            {
+                name: "agent",
+                desc: "Inspect and operate AI agent resources",
+                alias: "sessions <resource>",
+            },
         ],
     },
     {
@@ -50,6 +55,7 @@ const COMMAND_GROUPS = [
         commands: [
             { name: "up, deploy", desc: "Start services (optionally by stack)", alias: "[stack-name]" },
             { name: "down", desc: "Stop all tilt resources", alias: "" },
+            { name: "restart", desc: "Restart a running resource in the stack", alias: "<resource>" },
             { name: "status", desc: "Show status of services and stacks", alias: "" },
             { name: "logs", desc: "Print recent logs from the running stack", alias: "--json" },
         ],
@@ -131,6 +137,7 @@ export function showHelp() {
   ${chalk.cyan("$")} tdk project                       # Create master configs
   ${chalk.cyan("$")} tdk resource api --type backend   # Create a backend service
   ${chalk.cyan("$")} tdk resource app --type frontend  # Create a frontend app
+  ${chalk.cyan("$")} tdk resource bot --type agent     # Create an AI agent (sessions survive tdk down)
   ${chalk.cyan("$")} tdk stacks --services             # List stacks with their resources
   ${chalk.cyan("$")} tdk up my-stack                   # Start a stack
   ${chalk.cyan("$")} tdk networks                      # Show Traefik-routed URLs