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

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) {
@@ -154,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",
@@ -184,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",
                 }
                 : {}),
@@ -272,7 +285,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 +302,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, named volume) or postgres")
     .action(async (name, options) => {
     if (options.frameworks) {
         for (const f of listFrontendFrameworks()) {
@@ -322,6 +337,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 +373,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 +455,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,8 +640,8 @@ 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 packageJson = createPackageJson(resourceName, resourceType, scaffoldFrameworkId, prismaEnabled);
+        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, agentConfig);
         if (prismaEnabled && resourceType === "backend") {
             serviceJson.dependsOn = [`${resourceName}-migrator`];
         }
@@ -645,12 +678,19 @@ 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") {
+            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),
-                description: resourceType === "mcp" ? "Generating MCP server source" : "Generating backend source",
+                content: indexContent,
+                description: resourceType === "mcp"
+                    ? "Generating MCP server source"
+                    : resourceType === "agent"
+                        ? "Generating agent source"
+                        : "Generating backend source",
                 emoji: "💻",
             });
         }

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);
+});

package/cli/dist/mcp/tools.js

@@ -4,6 +4,7 @@ import { spawn } from "node:child_process";
 import { closeSync, existsSync, openSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { isAbsolute, join } from "node:path";
+import { createMachineEnvelope } from "../utils/machine-output.js";
 /** A service or stack name. A leading "-" is rejected so a value can never be read as a flag. */
 const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const SINCE = /^(\d+(\.\d+)?(ns|us|µs|ms|s|m|h))+$/;
@@ -131,6 +132,8 @@ export function buildUpArgs(args) {
         out.push(...only.map((name) => `--only=${name}`));
     if (flag(args.force, "force"))
         out.push("--force");
+    if (flag(args.dryRun, "dryRun"))
+        out.push("--dry-run");
     out.push("--json");
     return out;
 }
@@ -168,17 +171,13 @@ export async function startUp(args, deps = defaultUpDeps) {
     }
     child.unref();
     return {
-        data: {
-            schemaVersion: 1,
-            data: {
-                ok: true,
-                started: true,
-                pid: child.pid ?? null,
-                logFile,
-                next: "Poll the status tool until data.tilt.readiness.ready is true. Call down to stop it.",
-            },
-            errors: [],
-        },
+        data: createMachineEnvelope({
+            ok: true,
+            started: true,
+            pid: child.pid ?? null,
+            logFile,
+            next: "Poll the status tool until data.tilt.readiness.ready is true. Call down to stop it.",
+        }),
         isError: false,
     };
 }
@@ -245,6 +244,7 @@ export function createTdkTools(run = runTdkCli, up = defaultUpDeps) {
                     description: "Start only these services plus what they depend on and shared infrastructure",
                 },
                 force: { type: "boolean", description: "Replace a Tilt that is already running" },
+                dryRun: { type: "boolean", description: "Show what would be started without starting" },
                 waitSeconds: {
                     type: "number",
                     description: "How long to watch for an early failure before returning (default 15, max 60)",
@@ -255,8 +255,15 @@ export function createTdkTools(run = runTdkCli, up = defaultUpDeps) {
         {
             name: "down",
             description: "Stop the running stack, optionally selecting its project with projectPath.",
-            inputSchema: OBJECT({ projectPath: PROJECT_PATH }),
-            handler: viaCli(() => ["down", "--json"]),
+            inputSchema: OBJECT({
+                projectPath: PROJECT_PATH,
+                dryRun: { type: "boolean", description: "Show what would be stopped without stopping" },
+            }),
+            handler: viaCli((args) => [
+                "down",
+                "--json",
+                ...(flag(args.dryRun, "dryRun") ? ["--dry-run"] : []),
+            ]),
         },
         {
             name: "status",
@@ -290,5 +297,53 @@ export function createTdkTools(run = runTdkCli, up = defaultUpDeps) {
                 return ["resources", "--json", ...(stack ? [`--stack=${stack}`] : [])];
             }),
         },
+        {
+            name: "restart_resource",
+            description: "Restart a running resource in the stack (or trigger its rebuild). Set projectPath when the MCP server is not running from the project root.",
+            inputSchema: OBJECT({
+                projectPath: PROJECT_PATH,
+                resource: { type: "string", description: "Name of the resource to restart" },
+            }),
+            handler: viaCli((args) => {
+                const resource = optionalName(args.resource, "resource");
+                if (!resource)
+                    throw new Error("resource is required");
+                return ["restart", resource, "--json"];
+            }),
+        },
+        {
+            name: "list_agents",
+            description: "List AI agent resources (appType: 'agent') in the project with their stack, runtime, durability and port. Set projectPath when the MCP server is not running from the project root.",
+            inputSchema: OBJECT({
+                projectPath: PROJECT_PATH,
+                stack: { type: "string", description: "Only this stack" },
+            }),
+            handler: viaCli((args) => {
+                const stack = optionalName(args.stack, "stack");
+                return ["resources", "--type=agent", "--json", ...(stack ? [`--stack=${stack}`] : [])];
+            }),
+        },
+        {
+            name: "get_agent_sessions",
+            description: "Inspect session checkpoints from a running AI agent resource. Set projectPath when the MCP server is not running from the project root.",
+            inputSchema: OBJECT({
+                projectPath: PROJECT_PATH,
+                resource: { type: "string", description: "Name of the agent resource" },
+                sessionId: { type: "string", description: "Optional session ID to fetch" },
+            }),
+            handler: viaCli((args) => {
+                const resource = optionalName(args.resource, "resource");
+                if (!resource)
+                    throw new Error("resource is required");
+                const sessionId = optionalName(args.sessionId, "sessionId");
+                return [
+                    "agent",
+                    "sessions",
+                    resource,
+                    ...(sessionId ? [`--session-id=${sessionId}`] : []),
+                    "--json",
+                ];
+            }),
+        },
     ];
 }

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-report.js

@@ -1,4 +1,5 @@
 import { CONTAINER_RUNTIME_CHECK } from "./constants.js";
+import { SCHEMA_VERSION } from "./machine-output.js";
 /** Wait for concurrent probes to finish even if one throws, so they can release resources. */
 export async function collectDoctorChecks(machineChecks, projectChecks) {
     const checks = [];
@@ -28,7 +29,7 @@ function containerRuntimeReachable(checks) {
 /** Produce the same readiness decision for human and machine consumers. */
 export function createDoctorReport(checks, inProject, errors = [], portPlan, host) {
     return {
-        schemaVersion: 1,
+        schemaVersion: SCHEMA_VERSION,
         data: {
             ready: errors.length === 0 &&
                 checks.every((check) => check.didPass || check.isSkipped || check.isWarning),

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/json-output.js

@@ -1,6 +1,7 @@
 // Copyright (c) 2026 TDK Landscape contributors
 // SPDX-License-Identifier: MIT
 import { writeSync } from "node:fs";
+import { createMachineEnvelope, } from "./machine-output.js";
 /**
  * Returns an emitter that writes at most one `{schemaVersion, data, errors}` object to stdout. If the process
  * exits before anything was emitted (a preflight `process.exit`, Tilt ending early), a failure object is written
@@ -12,7 +13,7 @@ export function createJsonEmitter(failureCode, command) {
         if (emitted)
             return;
         emitted = true;
-        writeSync(1, `${JSON.stringify({ schemaVersion: 1, data, errors })}\n`);
+        writeSync(1, `${JSON.stringify(createMachineEnvelope(data, errors))}\n`);
     };
     process.once("exit", (code) => {
         emit({ ok: false }, [

package/cli/dist/utils/machine-output.js

@@ -1,8 +1,9 @@
 // Copyright (c) 2026 TDK Landscape contributors
 // SPDX-License-Identifier: MIT
 import { TdkError } from "./errors.js";
+export const SCHEMA_VERSION = 1;
 export function createMachineEnvelope(data, errors = []) {
-    return { schemaVersion: 1, data, errors };
+    return { schemaVersion: SCHEMA_VERSION, data, errors };
 }
 export function toMachineError(error) {
     if (error instanceof TdkError) {

package/cli/dist/utils/project-templates.js

@@ -25,4 +25,8 @@ export const PROJECT_TEMPLATES = {
         bundledPath: "examples/tdk-example",
         description: "Hono + Postgres + NATS worker + Vite example with a routed write path",
     },
+    "agent-stack": {
+        repo: "https://github.com/tdk-landscape/tdk-agent-stack.git",
+        description: "AI agent stack: Bun agent + MCP tool server + Postgres + NATS",
+    },
 };

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) {