@tdk-landscape/tdk-cli-core 1.3.171 → 1.3.173

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

@@ -3,12 +3,194 @@
  * 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) {
+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/ai-agents.md):
+// 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
@@ -82,7 +264,7 @@ const server = createServer(async (req, res) => {
     }
 
     if (url.pathname === '/ready') {
-      const ok = !draining && store.ready();
+      const ok = !draining && (await store.ready());
       return sendJson(res, ok ? 200 : 503, { ready: ok, durability: DURABILITY });
     }
 
@@ -96,18 +278,18 @@ const server = createServer(async (req, res) => {
       }
       const body = await readJson(req);
       const input = String(body.input ?? '');
-      const checkpoint = store.load(sessionId);
+      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() });
-      store.save(checkpoint);
+      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 = store.load(sessionId);
+      const checkpoint = await store.load(sessionId);
       return sendJson(res, 200, { sessionId, turns: checkpoint.messages.length / 2, messages: checkpoint.messages });
     }
 

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

@@ -10,9 +10,7 @@ export const AGENT_RUNTIMES = {
     custom: customAgentRuntime,
 };
 export const DEFAULT_AGENT_RUNTIME = "custom";
-// `postgres` is deliberately absent: the scaffold has no Postgres session store yet (#1256), so offering it would produce an
-// agent that answers every turn with a 500. Add it here together with the store.
-export const AGENT_DURABILITY_OPTIONS = ["files"];
+export const AGENT_DURABILITY_OPTIONS = ["files", "postgres"];
 export function resolveAgentRuntime(runtimeId) {
     const id = runtimeId ?? DEFAULT_AGENT_RUNTIME;
     const provider = AGENT_RUNTIMES[id];

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

@@ -60,7 +60,7 @@ export function resolveBackendFramework(resourceType, frameworkId, language) {
     // `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) {
+        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",
             ]);

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" },
         ],

package/cli/dist/commands/resource.js

@@ -162,10 +162,11 @@ function requireGeneratedViteConfig(configPath) {
         "Run tdk up <stack> once, or point this script at your own Vite config to build on the host.";
     return `bun -e 'if(!require("fs").existsSync(${JSON.stringify(configPath)})){console.error(${JSON.stringify(message)});process.exit(1)}'`;
 }
-export function createPackageJson(name, type, frameworkId, prismaEnabled = false) {
+export function createPackageJson(name, type, frameworkId, prismaEnabled = false, agentConfig) {
     const isFrontend = type === "frontend";
     const framework = resolveFrontendFramework(type, frameworkId);
     const backendFramework = resolveBackendFramework(type, frameworkId);
+    const isPostgresAgent = type === "agent" && agentConfig?.durability === "postgres";
     return {
         name: `@project/${name}`,
         version: "0.0.1",
@@ -192,11 +193,15 @@ export function createPackageJson(name, type, frameworkId, prismaEnabled = false
         dependencies: {
             ...(isFrontend ? {} : (backendFramework?.dependencies ?? { hono: "^4.0.0" })),
             ...(framework?.dependencies ?? {}),
-            ...(prismaEnabled
+            ...(prismaEnabled || isPostgresAgent
                 ? {
-                    prisma: "^7.5.0",
-                    "@prisma/client": "^7.5.0",
-                    "@prisma/adapter-pg": "^7.5.0",
+                    ...(prismaEnabled
+                        ? {
+                            prisma: "^7.5.0",
+                            "@prisma/client": "^7.5.0",
+                            "@prisma/adapter-pg": "^7.5.0",
+                        }
+                        : {}),
                     pg: "^8.13.0",
                 }
                 : {}),
@@ -298,7 +303,7 @@ export const resourceCommand = new Command("resource")
     .option("--port <port>", "Port for the resource, within its type's range (default: next free port in that range)")
     .option("--feature <feature...>", "Enable a resource feature (for example: prisma)")
     .option("--runtime <id>", "Agent runtime (for agent only): custom (default)")
-    .option("--durability <kind>", "Where agent sessions are checkpointed (for agent only): files (default, a named volume that survives tdk down)")
+    .option("--durability <kind>", "Where agent sessions are checkpointed (for agent only): files (default, named volume) or postgres")
     .action(async (name, options) => {
     if (options.frameworks) {
         for (const f of listFrontendFrameworks()) {
@@ -636,7 +641,7 @@ This file contains the resource configuration for TDK.
         const requestedFeatures = Array.isArray(options.feature) ? options.feature : [];
         const prismaEnabled = requestedFeatures.includes("prisma");
         const serviceJson = createServiceJson(resourceName, resourceType, stackName, assignedPort, [...(dddEnabled ? ["ddd"] : []), ...requestedFeatures], scaffoldFrameworkId, options.language === undefined ? undefined : backendLanguage?.id, agentConfig);
-        const packageJson = createPackageJson(resourceName, resourceType, scaffoldFrameworkId, prismaEnabled);
+        const packageJson = createPackageJson(resourceName, resourceType, scaffoldFrameworkId, prismaEnabled, agentConfig);
         if (prismaEnabled && resourceType === "backend") {
             serviceJson.dependsOn = [`${resourceName}-migrator`];
         }
@@ -674,10 +679,13 @@ This file contains the resource configuration for TDK.
         ];
         // Add source files based on resource type
         if (resourceType === "backend" || resourceType === "mcp" || resourceType === "agent") {
+            const indexContent = resourceType === "agent"
+                ? (backendFramework?.createIndex ?? getBackendIndexTemplate)(resourceName, agentConfig?.durability)
+                : (backendFramework?.createIndex ?? getBackendIndexTemplate)(resourceName);
             tasks.push({
                 type: "text",
                 filename: "src/index.ts",
-                content: (backendFramework?.createIndex ?? getBackendIndexTemplate)(resourceName),
+                content: indexContent,
                 description: resourceType === "mcp"
                     ? "Generating MCP server source"
                     : resourceType === "agent"

package/cli/dist/commands/restart.js

@@ -0,0 +1,79 @@
+// Copyright (c) 2026 TDK Landscape contributors
+// SPDX-License-Identifier: MIT
+import chalk from "chalk";
+import { Command } from "commander";
+import { STANDARD_PORTS } from "../utils/constants.js";
+import { errorFactories, runCommand, TdkError } from "../utils/errors.js";
+import { createMachineEnvelope, writeMachineError } from "../utils/machine-output.js";
+import { findProjectRoot } from "../utils/paths.js";
+import { isTiltAvailable, runTilt } from "../utils/tilt.js";
+import { isTiltConnectionFailure } from "../utils/tilt-logs.js";
+import { tiltUnreachableMessage } from "../utils/tilt-unreachable-message.js";
+export const restartCommand = new Command("restart")
+    .description("Restart a running resource in the stack")
+    .argument("<resource>", "Name of the resource (service) to restart")
+    .option("--port <n>", "Tilt UI port (default: TILT_PORT or 10350)")
+    .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 portText = options.port ?? process.env.TILT_PORT ?? String(STANDARD_PORTS.tiltUi);
+        let tiltAvailable = false;
+        try {
+            tiltAvailable = await isTiltAvailable();
+        }
+        catch {
+            tiltAvailable = false;
+        }
+        if (!tiltAvailable) {
+            // isTiltAvailable collapses missing binary and nonzero version into false.
+            // Report TILT_NOT_RUNNING for both; a missing binary is rare and still surfaces via doctor.
+            const msg = tiltUnreachableMessage(portText);
+            if (options.json) {
+                console.log(JSON.stringify(createMachineEnvelope(null, [{ code: "TILT_NOT_RUNNING", message: msg }])));
+                process.exit(1);
+            }
+            throw new TdkError(msg, ["Start the stack first with: tdk up"]);
+        }
+        const result = await runTilt("trigger", [resourceName, "--port", portText], {
+            inheritStdio: false,
+        });
+        if (result.exitCode !== 0) {
+            const detail = result.stderr.trim();
+            if (!detail || isTiltConnectionFailure(detail)) {
+                const msg = tiltUnreachableMessage(portText);
+                if (options.json) {
+                    console.log(JSON.stringify(createMachineEnvelope(null, [{ code: "TILT_NOT_RUNNING", message: msg }])));
+                    process.exit(1);
+                }
+                throw new TdkError(msg, ["Start the stack first with: tdk up"]);
+            }
+            if (options.json) {
+                console.log(JSON.stringify(createMachineEnvelope(null, [{ code: "TILT_TRIGGER_FAILED", message: detail }])));
+                process.exit(1);
+            }
+            throw new TdkError(`Failed to restart ${resourceName}: ${detail}`);
+        }
+        if (options.json) {
+            console.log(JSON.stringify(createMachineEnvelope({ resource: resourceName, restarted: true })));
+            return;
+        }
+        console.log(chalk.green(`✓ Triggered restart for ${resourceName}`));
+    };
+    if (options.json) {
+        try {
+            await action();
+        }
+        catch (err) {
+            writeMachineError(err);
+        }
+        return;
+    }
+    await runCommand(action);
+});