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

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

@@ -0,0 +1,151 @@
+/**
+ * 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) {
+    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):
+//   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 && 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 = 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);
+      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);
+      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,36 @@
+// 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";
+// `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 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) {
+            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/commands/help.js

@@ -131,6 +131,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

package/cli/dist/commands/resource.js

@@ -4,6 +4,7 @@ import { existsSync, mkdirSync } from "node:fs";
 import { isAbsolute, relative, resolve } from "node:path";
 import chalk from "chalk";
 import { Command } from "commander";
+import { DEFAULT_AGENT_RUNTIME, resolveAgentDurability, resolveAgentRuntime, } from "../agent-runtimes/registry.js";
 import { resolveBackendFramework } from "../backend-frameworks/registry.js";
 import { getBackendIndexTemplate } from "../backend-languages/bun.js";
 import { resolveBackendLanguage } from "../backend-languages/registry.js";
@@ -56,6 +57,10 @@ export const TYPE_SPECIFIC = {
     mcp: {
         healthCheckPath: "/health",
     },
+    // /ready is the readiness route (checkpoint store reachable); /health is liveness only, so an idle agent stays healthy.
+    agent: {
+        healthCheckPath: "/health",
+    },
     [BRING_YOUR_OWN_TYPE]: {
         healthCheckPath: "/health",
     },
@@ -84,7 +89,7 @@ export function resolveResourcePort(resourceType, value, assignedPort, resources
     }
     return port;
 }
-export function createServiceJson(name, type, stack, port, extraFeatures = [], frameworkId, languageId) {
+export function createServiceJson(name, type, stack, port, extraFeatures = [], frameworkId, languageId, agent) {
     const framework = resolveFrontendFramework(type, frameworkId);
     // Only an explicit selection is persisted: a missing `language` has always meant Bun.
     const language = languageId === undefined ? undefined : resolveBackendLanguage(type, languageId);
@@ -123,8 +128,11 @@ export function createServiceJson(name, type, stack, port, extraFeatures = [], f
         stack,
         port,
         ...(framework ? { framework: framework.id } : {}),
-        ...(backendFramework && type !== "mcp" ? { framework: backendFramework.id } : {}),
+        ...(backendFramework && type !== "mcp" && type !== "agent"
+            ? { framework: backendFramework.id }
+            : {}),
         ...(language ? { language: language.id } : {}),
+        ...(type === "agent" && agent ? { agent } : {}),
     };
 }
 export function createByoServiceJson(name, stack, port, options) {
@@ -272,7 +280,7 @@ export function parseResourceType(type) {
 export const resourceCommand = new Command("resource")
     .description("Create a new resource (service) from scratch, or register an existing one")
     .argument("[name]", "Resource name (kebab-case)")
-    .option("-t, --type <type>", "Resource type: backend, frontend, worker, mcp, bring-your-own, sdk", "backend")
+    .option("-t, --type <type>", "Resource type: backend, frontend, worker, mcp, agent, bring-your-own, sdk", "backend")
     .option("--framework <id>", "Framework: frontend react (default), vue, svelte, preact, lit, solid, qwik, vanilla, tanstack-router (see --frameworks); backend hono (default), express, elysia, fastify, nestjs, koa, h3")
     .option("--frameworks", "List registered frontend frameworks and exit")
     .option("--language <id>", "Backend language: bun (default), python, go, rust")
@@ -289,6 +297,8 @@ export const resourceCommand = new Command("resource")
     .option("--image <name>", "Docker image name instead of building from Dockerfile (for bring-your-own)")
     .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)")
     .action(async (name, options) => {
     if (options.frameworks) {
         for (const f of listFrontendFrameworks()) {
@@ -322,6 +332,21 @@ export const resourceCommand = new Command("resource")
             assertValid(validateResourceName(resourceName));
         }
         const resourceType = parseResourceType(options.type);
+        if (resourceType !== "agent" &&
+            (options.runtime !== undefined || options.durability !== undefined)) {
+            throw new TdkError("--runtime and --durability can only be used with --type agent.", [
+                "Drop --runtime and --durability, or pass --type agent",
+            ]);
+        }
+        // Validate the agent options before anything is written, so a bad flag leaves no half-scaffolded directory.
+        let agentConfig;
+        if (resourceType === "agent") {
+            resolveAgentRuntime(options.runtime);
+            agentConfig = {
+                runtime: options.runtime ?? DEFAULT_AGENT_RUNTIME,
+                durability: resolveAgentDurability(options.durability),
+            };
+        }
         let frameworkOption = options.framework;
         if (resourceType === "frontend" &&
             frameworkOption === undefined &&
@@ -343,7 +368,9 @@ export const resourceCommand = new Command("resource")
         const backendFramework = resolveBackendFramework(resourceType, frameworkOption, backendLanguage);
         // The id passed on to the file generators. An mcp resource has one fixed scaffold and no `framework` setting, so it passes none
         // (its provider is selected by the resource type itself).
-        const scaffoldFrameworkId = resourceType === "mcp" ? undefined : (frontendFramework?.id ?? backendFramework?.id);
+        const scaffoldFrameworkId = resourceType === "mcp" || resourceType === "agent"
+            ? undefined
+            : (frontendFramework?.id ?? backendFramework?.id);
         let dddEnabled = false;
         if (options.ddd) {
             if (resourceType !== "backend" && resourceType !== "worker") {
@@ -423,6 +450,7 @@ export const resourceCommand = new Command("resource")
                 frontend: `apps/${resourceName}`,
                 worker: `workers/${resourceName}`,
                 mcp: `services/${stackName}/${resourceName}`,
+                agent: `services/${stackName}/${resourceName}`,
                 [BRING_YOUR_OWN_TYPE]: `services/${stackName}/${resourceName}`,
                 sdk: `packages/${resourceName}`,
             };
@@ -607,7 +635,7 @@ This file contains the resource configuration for TDK.
         // Prepare file generation tasks
         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);
+        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);
         if (prismaEnabled && resourceType === "backend") {
             serviceJson.dependsOn = [`${resourceName}-migrator`];
@@ -645,12 +673,16 @@ This file contains the resource configuration for TDK.
             },
         ];
         // Add source files based on resource type
-        if (resourceType === "backend" || resourceType === "mcp") {
+        if (resourceType === "backend" || resourceType === "mcp" || resourceType === "agent") {
             tasks.push({
                 type: "text",
                 filename: "src/index.ts",
                 content: (backendFramework?.createIndex ?? getBackendIndexTemplate)(resourceName),
-                description: resourceType === "mcp" ? "Generating MCP server source" : "Generating backend source",
+                description: resourceType === "mcp"
+                    ? "Generating MCP server source"
+                    : resourceType === "agent"
+                        ? "Generating agent source"
+                        : "Generating backend source",
                 emoji: "💻",
             });
         }

package/cli/dist/types/index.js

@@ -9,6 +9,7 @@ export const RESOURCE_CONFIG_APP_TYPES = [
     "worker",
     "migrator",
     "mcp",
+    "agent",
     "bring-your-own",
 ];
 export const CREATABLE_RESOURCE_TYPES = [
@@ -16,6 +17,7 @@ export const CREATABLE_RESOURCE_TYPES = [
     "frontend",
     "worker",
     "mcp",
+    "agent",
     "bring-your-own",
 ];
 export function isCreatableResourceType(value) {

package/cli/dist/utils/constants.js

@@ -45,6 +45,7 @@ export const VALID_RESOURCE_TYPES = [
     "worker",
     "migrator",
     "mcp",
+    "agent",
     BRING_YOUR_OWN_TYPE,
 ];
 // Frontend/library/sdk services are served statically or consumed as
@@ -56,6 +57,7 @@ export const REQUIRED_PACKAGE_SCRIPTS = {
     worker: ["dev", "build", "start"],
     migrator: ["dev", "build", "start"],
     mcp: ["dev", "build", "start"],
+    agent: ["dev", "build", "start"],
     frontend: ["dev", "build"],
     library: ["dev", "build"],
     sdk: ["dev", "build"],
@@ -76,6 +78,8 @@ export const PORT_RANGES = {
     backend: { base: 4000, min: 4000, max: 4999, range: "4000-4999" },
     // An MCP server is an HTTP service, so it shares the backend-compatible range with bring-your-own.
     mcp: { base: 4000, min: 4000, max: 5999, range: "4000-5999" },
+    // An agent serves /health and /ready over HTTP (see agent-runtimes/custom.ts), so it shares the same range.
+    agent: { base: 4000, min: 4000, max: 5999, range: "4000-5999" },
     [BRING_YOUR_OWN_TYPE]: { base: 4000, min: 4000, max: 5999, range: "4000-5999" },
     worker: { base: 6000, min: 6000, max: 6999, range: "6000-6999" },
     health: { base: 5000, min: 5000, max: 5999, range: "5000-5999" },

package/cli/dist/utils/doctor-wiring.js

@@ -232,7 +232,7 @@ export function checkDuplicateResourceNames(projectRoot = findProjectRoot() ?? p
         fix: 'Give each resource its own "appName" in its service.json. The name becomes the Compose service and the Traefik router, so two resources with one name collide',
     };
 }
-/** A resource that gets a Traefik route to its own `port`: a backend, an mcp server, or a bring-your-own resource that is not opted out. */
+/** A resource that gets a Traefik route to its own `port`: a backend, an mcp server, an agent, or a bring-your-own resource that is not opted out. */
 function isRoutedToPort(resource) {
     const appType = resource.config?.appType;
     if (isApiServiceType(appType))

package/cli/dist/utils/resource-kind.js

@@ -5,5 +5,5 @@
  * Protocol endpoint, which the engine builds, routes and health-checks exactly like a backend).
  */
 export function isApiServiceType(appType) {
-    return appType === "backend" || appType === "mcp";
+    return appType === "backend" || appType === "mcp" || appType === "agent";
 }

package/cli/dist/utils/service-manifest.js

@@ -15,6 +15,7 @@ const DEPRECATED_FIELDS = {
 };
 const KNOWN_SERVICE_FIELDS = new Set([
     "$schema",
+    "agent",
     "apiBasePath",
     "apiPath",
     "appName",

package/cli/dist/utils/status-ports.js

@@ -9,7 +9,9 @@ export function buildServicePorts(resource, ingressHttp) {
         const { appBase, apiBase } = resolveSubdomainBases(ingressHttp);
         url = `${isApiServiceType(appType) ? apiBase : appBase}${resolveServicePath(resource)}`;
     }
-    return { url, containerPort: resource.port ?? resource.config?.port ?? null, hostPort: null };
+    const containerPort = resource.port ?? resource.config?.port ?? null;
+    const directUrl = !routable && containerPort ? `http://localhost:${containerPort}` : null;
+    return { url, containerPort, hostPort: null, directUrl };
 }
 /** Ports a client should forward or open: ingress, Tilt UI, and the published datastore. Not one per service. */
 export function buildStackPorts(plan, tiltPort) {