@tapi-dev/sdk 0.1.34 → 0.1.38

package/dist/cli.js

@@ -3,7 +3,7 @@ import { spawn } from "node:child_process";
 import { createServer } from "node:http";
 import { createServer as createNetServer } from "node:net";
 import { createHash, randomUUID } from "node:crypto";
-import { createReadStream, createWriteStream, existsSync, readFileSync, readdirSync } from "node:fs";
+import { createReadStream, createWriteStream, existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
 import { mkdir, readFile, readdir, rename, rm, stat, statfs, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
@@ -21,7 +21,7 @@ const DEFAULT_FIREBASE_API_KEY = "AIzaSyCDZR8lWyVQcWYfFdNZa4vuL4IWEC0h6gE";
 const DEFAULT_CHANNEL = "pilot";
 const SUPPORTED_STUDIO_PLATFORM = "windows-x86_64";
 const DEFAULT_INSTALL_AUTH_TIMEOUT_MS = 120_000;
-const PORTABLE_STUDIO_SERVER_READY_TIMEOUT_MS = 30_000;
+export const PORTABLE_STUDIO_SERVER_READY_TIMEOUT_MS = 120_000;
 const PORTABLE_STUDIO_SERVER_READY_INTERVAL_MS = 250;
 const DOWNLOAD_STALL_TIMEOUT_MS = 30_000;
 const DOWNLOAD_PROGRESS_LOG_BYTES = 50 * 1024 * 1024;
@@ -33,6 +33,10 @@ const WINDOWS_SERVICE_COMMAND_TIMEOUT_MS = 30_000;
 const MANAGED_RELEASE_MARKER = ".tapi-managed-release";
 const MIN_EXTRACTION_REQUIRED_BYTES = 1024 * 1024 * 1024;
 const EXTRACTION_REQUIRED_MULTIPLIER = 3;
+const RETIRED_TRIGGER_TARGET_FIELD = "api" + "Request";
+const RUNTIME_OWNER_FIELDS = ["owner"];
+const RETIRED_RUNTIME_OWNER_ALIAS_FIELDS = ["runtimeOwner", "runtime_owner"];
+const SERVICE_RUN_RUNTIME_OWNER = "service_run";
 class StudioInstallApprovalError extends Error {
     code;
     status;
@@ -113,6 +117,50 @@ async function withCliSpinner(message, work) {
         throw error;
     }
 }
+async function withSdkAuth(options) {
+    if (options.authToken?.trim()) {
+        return { ...options, authToken: options.authToken.trim() };
+    }
+    const envAuthToken = envString("TAPI_FIREBASE_ID_TOKEN");
+    if (envAuthToken) {
+        return { ...options, authToken: envAuthToken };
+    }
+    const credentials = await requireSdkFirebaseCredentials();
+    return { ...options, authToken: credentials.idToken };
+}
+async function requireSdkFirebaseCredentials() {
+    const credentials = await refreshCachedFirebaseCredentials();
+    if (!credentials) {
+        throw new Error(`Tapi sign-in is required. Run \`tapi login\`, then retry.`);
+    }
+    await writeStudioAuthCache(credentials);
+    return credentials;
+}
+async function runLogin() {
+    try {
+        const credentials = await withCliSpinner("Signing in to Tapi", () => authenticateSdkUser());
+        console.log(`Signed in to Tapi as ${credentials.uid}.`);
+        return 0;
+    }
+    catch (error) {
+        console.error(formatError(error));
+        return 1;
+    }
+}
+async function authenticateSdkUser() {
+    const cached = await refreshCachedFirebaseCredentials();
+    if (cached) {
+        await writeStudioAuthCache(cached);
+        return cached;
+    }
+    const browserAuth = await browserGoogleSignIn();
+    if (!browserAuth.idToken) {
+        throw new Error(browserAuth.error || browserAuth.detail || "Browser sign-in did not return a Google ID token.");
+    }
+    const credentials = await exchangeGoogleToFirebase(browserAuth.idToken, browserAuth.accessToken);
+    await writeStudioAuthCache(credentials);
+    return credentials;
+}
 export async function runCli(argv = process.argv.slice(2)) {
     const [command, subcommand, ...rest] = argv;
     if (!command || command === "help" || command === "--help" || command === "-h") {
@@ -123,6 +171,18 @@ export async function runCli(argv = process.argv.slice(2)) {
         console.log(sdkVersion);
         return 0;
     }
+    if (command === "login") {
+        if (hasHelpFlag([subcommand, ...rest])) {
+            printLoginHelp();
+            return 0;
+        }
+        if (subcommand) {
+            console.error(`Unexpected login argument: ${subcommand}`);
+            printLoginHelp();
+            return 1;
+        }
+        return runLogin();
+    }
     if (command === "doctor") {
         if (hasHelpFlag([subcommand, ...rest])) {
             printStudioHelp();
@@ -144,8 +204,12 @@ export async function runCli(argv = process.argv.slice(2)) {
         }
         return runServiceCommand(subcommand, rest);
     }
-    if (command === "services" || command === "apis") {
-        if (!subcommand || subcommand === "help" || subcommand === "--help" || subcommand === "-h" || hasHelpFlag(rest)) {
+    if (command === "services") {
+        if (!subcommand || subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
+            printServicesHelp();
+            return 0;
+        }
+        if (hasHelpFlag(rest)) {
             printServicesHelp();
             return 0;
         }
@@ -155,20 +219,71 @@ export async function runCli(argv = process.argv.slice(2)) {
         if (subcommand === "sync") {
             return syncServiceCatalog(rest);
         }
-        if (subcommand === "generate") {
-            return generateServiceClient(rest);
-        }
         console.error(`Unknown service-run command: ${subcommand}`);
         printServicesHelp();
         return 1;
     }
+    if (command === "tapp") {
+        if (!subcommand || subcommand === "help" || subcommand === "--help" || subcommand === "-h" || hasHelpFlag(rest)) {
+            printTappHelp();
+            return 0;
+        }
+        if (subcommand === "create") {
+            return createTapp(rest);
+        }
+        if (subcommand === "service") {
+            const serviceCommand = rest[0] || "";
+            if (serviceCommand === "add") {
+                return addTappService(rest.slice(1));
+            }
+        }
+        if (subcommand === "queue") {
+            const queueCommand = rest[0] || "";
+            if (queueCommand === "add") {
+                return addTappQueue(rest.slice(1));
+            }
+        }
+        console.error(`Unknown Tapp command: ${[subcommand, ...rest].filter(Boolean).join(" ")}`);
+        printTappHelp();
+        return 1;
+    }
+    if (command === "queue") {
+        if (!subcommand || subcommand === "help" || subcommand === "--help" || subcommand === "-h" || hasHelpFlag(rest)) {
+            printQueueHelp();
+            return 0;
+        }
+        if (subcommand === "create") {
+            return createQueue(rest);
+        }
+        console.error(`Unknown queue command: ${subcommand}`);
+        printQueueHelp();
+        return 1;
+    }
+    if (command === "runner") {
+        if (!subcommand || subcommand === "help" || subcommand === "--help" || subcommand === "-h" || hasHelpFlag(rest)) {
+            printRunnerHelp();
+            return 0;
+        }
+        if (subcommand === "setup") {
+            return runRunnerSetup(rest);
+        }
+        if (subcommand === "slot") {
+            const slotCommand = rest[0] || "";
+            if (slotCommand === "set") {
+                return setRunnerSlot(rest.slice(1));
+            }
+        }
+        console.error(`Unknown runner command: ${[subcommand, ...rest].filter(Boolean).join(" ")}`);
+        printRunnerHelp();
+        return 1;
+    }
     if (command === "triggers") {
         if (!subcommand || subcommand === "help" || subcommand === "--help" || subcommand === "-h" || hasHelpFlag(rest)) {
             printTriggersHelp();
             return 0;
         }
         if (subcommand === "sync") {
-            return syncApiTriggers(rest);
+            return syncServiceTriggers(rest);
         }
         console.error(`Unknown triggers command: ${subcommand}`);
         printTriggersHelp();
@@ -363,16 +478,406 @@ export function parseStudioOptions(args) {
         workspace,
         workspaceRoot: workspace?.root,
         projectId,
-        projectSlug,
-        workspaceMode: Boolean(projectId || workspace),
+        projectSlug,
+        workspaceMode: Boolean(projectId || workspace),
+    };
+}
+function parseServiceOptions(args) {
+    let operation = "";
+    const workspace = loadWorkspace();
+    let apiBaseUrl = envString("TAPI_BASE_URL") || workspace?.apiBaseUrl || DEFAULT_STUDIO_API_BASE_URL;
+    let projectId = envString("TAPI_PROJECT_ID") || workspace?.projectId || "";
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!arg)
+            continue;
+        if (arg === "--api-base-url" || arg === "--server") {
+            apiBaseUrl = requireOptionValue(args, ++index, arg);
+            continue;
+        }
+        if (arg.startsWith("--api-base-url=")) {
+            apiBaseUrl = arg.slice("--api-base-url=".length);
+            continue;
+        }
+        if (arg.startsWith("--server=")) {
+            apiBaseUrl = arg.slice("--server=".length);
+            continue;
+        }
+        if (arg === "--project") {
+            projectId = normalizeProjectValue(requireOptionValue(args, ++index, "--project"), "project");
+            continue;
+        }
+        if (arg.startsWith("--project=")) {
+            projectId = normalizeProjectValue(arg.slice("--project=".length), "project");
+            continue;
+        }
+        if (arg.startsWith("--")) {
+            throw new Error(`Unknown services option: ${arg}`);
+        }
+        if (!operation) {
+            operation = arg;
+            continue;
+        }
+        throw new Error(`Unexpected services argument: ${arg}`);
+    }
+    if (!operation) {
+        throw new Error("services describe requires a service run like schwab.place_order.");
+    }
+    if (!projectId) {
+        throw new Error("services describe requires --project, TAPI_PROJECT_ID, or .tapi/project.json.");
+    }
+    return {
+        operation,
+        options: {
+            apiBaseUrl: normalizeHttpUrl(apiBaseUrl, "Tapi API base URL"),
+            projectId,
+        },
+    };
+}
+async function describeServiceOperation(args) {
+    try {
+        const { operation, options } = parseServiceOptions(args);
+        const authenticated = await withSdkAuth(options);
+        const client = new TapiClient({
+            baseUrl: authenticated.apiBaseUrl,
+            authToken: authenticated.authToken,
+            tappId: authenticated.projectId,
+            projectId: authenticated.projectId,
+        });
+        const description = await withCliSpinner(`Fetching Tapi service-run contract for ${operation}`, () => client.services.describe(operation));
+        console.log(JSON.stringify(description, null, 2));
+        return 0;
+    }
+    catch (error) {
+        console.error(formatError(error));
+        return 1;
+    }
+}
+function parseApiWorkspaceOptions(args) {
+    const workspace = loadWorkspace();
+    let apiBaseUrl = envString("TAPI_BASE_URL") || workspace?.apiBaseUrl || DEFAULT_STUDIO_API_BASE_URL;
+    let projectId = envString("TAPI_PROJECT_ID") || workspace?.projectId || "";
+    let catalogPath = workspace?.config.services?.catalog || ".tapi/services/catalog.json";
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!arg)
+            continue;
+        if (arg === "--api-base-url" || arg === "--server") {
+            apiBaseUrl = requireOptionValue(args, ++index, arg);
+            continue;
+        }
+        if (arg.startsWith("--api-base-url=")) {
+            apiBaseUrl = arg.slice("--api-base-url=".length);
+            continue;
+        }
+        if (arg.startsWith("--server=")) {
+            apiBaseUrl = arg.slice("--server=".length);
+            continue;
+        }
+        if (arg === "--project") {
+            projectId = normalizeProjectValue(requireOptionValue(args, ++index, "--project"), "project");
+            continue;
+        }
+        if (arg.startsWith("--project=")) {
+            projectId = normalizeProjectValue(arg.slice("--project=".length), "project");
+            continue;
+        }
+        if (arg === "--catalog") {
+            catalogPath = requireOptionValue(args, ++index, "--catalog");
+            continue;
+        }
+        if (arg.startsWith("--catalog=")) {
+            catalogPath = arg.slice("--catalog=".length);
+            continue;
+        }
+        throw new Error(`Unknown services option: ${arg}`);
+    }
+    if (!projectId) {
+        throw new Error("services command requires --project, TAPI_PROJECT_ID, or .tapi/project.json.");
+    }
+    const root = workspace?.root || process.cwd();
+    return {
+        apiBaseUrl: normalizeHttpUrl(apiBaseUrl, "Tapi API base URL"),
+        projectId,
+        catalogPath: resolve(root, catalogPath),
+    };
+}
+async function syncServiceCatalog(args) {
+    try {
+        const options = await withSdkAuth(parseApiWorkspaceOptions(args));
+        const catalog = await withCliSpinner("Fetching Tapi service-run catalog", () => fetchApiCatalog(options));
+        await writeJsonFile(options.catalogPath, catalog);
+        console.log(`Synced Tapi service-run catalog: ${options.catalogPath}`);
+        return 0;
+    }
+    catch (error) {
+        console.error(formatError(error));
+        return 1;
+    }
+}
+function parseTappServiceAddOptions(args) {
+    const workspace = loadWorkspace();
+    let apiBaseUrl = envString("TAPI_BASE_URL") || workspace?.apiBaseUrl || DEFAULT_STUDIO_API_BASE_URL;
+    let tappId = "";
+    let serviceCall = "";
+    let serviceMapId = "";
+    let entry = "";
+    let expectedRevision = "";
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!arg)
+            continue;
+        if (arg === "--api-base-url" || arg === "--server") {
+            apiBaseUrl = requireOptionValue(args, ++index, arg);
+            continue;
+        }
+        if (arg.startsWith("--api-base-url=")) {
+            apiBaseUrl = arg.slice("--api-base-url=".length);
+            continue;
+        }
+        if (arg.startsWith("--server=")) {
+            apiBaseUrl = arg.slice("--server=".length);
+            continue;
+        }
+        if (arg === "--service-map") {
+            serviceMapId = requireOptionValue(args, ++index, "--service-map");
+            continue;
+        }
+        if (arg.startsWith("--service-map=")) {
+            serviceMapId = arg.slice("--service-map=".length);
+            continue;
+        }
+        if (arg === "--entry") {
+            entry = requireOptionValue(args, ++index, "--entry");
+            continue;
+        }
+        if (arg.startsWith("--entry=")) {
+            entry = arg.slice("--entry=".length);
+            continue;
+        }
+        if (arg === "--expected-revision") {
+            expectedRevision = requireOptionValue(args, ++index, "--expected-revision");
+            continue;
+        }
+        if (arg.startsWith("--expected-revision=")) {
+            expectedRevision = arg.slice("--expected-revision=".length);
+            continue;
+        }
+        if (arg.startsWith("--")) {
+            throw new Error(`Unknown tapp service add option: ${arg}`);
+        }
+        if (!tappId) {
+            tappId = normalizeProjectValue(arg, "tapp");
+            continue;
+        }
+        if (!serviceCall) {
+            serviceCall = arg.trim();
+            continue;
+        }
+        throw new Error(`Unexpected tapp service add argument: ${arg}`);
+    }
+    if (!tappId) {
+        throw new Error("tapp service add requires a Tapp id.");
+    }
+    if (!serviceCall || !serviceCall.includes(".")) {
+        throw new Error("tapp service add requires a service call like schwab.place_order.");
+    }
+    if (!serviceMapId) {
+        throw new Error("tapp service add requires --service-map.");
+    }
+    if (!entry) {
+        throw new Error("tapp service add requires --entry.");
+    }
+    return {
+        apiBaseUrl: normalizeHttpUrl(apiBaseUrl, "Tapi API base URL"),
+        tappId,
+        serviceCall,
+        serviceMapId,
+        entry,
+        expectedRevision,
+    };
+}
+function parseTappCreateOptions(args) {
+    const workspace = loadWorkspace();
+    let apiBaseUrl = envString("TAPI_BASE_URL") || workspace?.apiBaseUrl || DEFAULT_STUDIO_API_BASE_URL;
+    let tappId = envString("TAPI_PROJECT_ID") || workspace?.projectId || "";
+    let name = "";
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!arg)
+            continue;
+        if (arg === "--api-base-url" || arg === "--server") {
+            apiBaseUrl = requireOptionValue(args, ++index, arg);
+            continue;
+        }
+        if (arg.startsWith("--api-base-url=")) {
+            apiBaseUrl = arg.slice("--api-base-url=".length);
+            continue;
+        }
+        if (arg.startsWith("--server=")) {
+            apiBaseUrl = arg.slice("--server=".length);
+            continue;
+        }
+        if (arg === "--tapp-id" || arg === "--project") {
+            tappId = normalizeProjectValue(requireOptionValue(args, ++index, arg), "tapp");
+            continue;
+        }
+        if (arg.startsWith("--tapp-id=")) {
+            tappId = normalizeProjectValue(arg.slice("--tapp-id=".length), "tapp");
+            continue;
+        }
+        if (arg.startsWith("--project=")) {
+            tappId = normalizeProjectValue(arg.slice("--project=".length), "tapp");
+            continue;
+        }
+        if (arg === "--name") {
+            name = requireOptionValue(args, ++index, "--name").trim();
+            continue;
+        }
+        if (arg.startsWith("--name=")) {
+            name = arg.slice("--name=".length).trim();
+            continue;
+        }
+        if (arg.startsWith("--")) {
+            throw new Error(`Unknown tapp create option: ${arg}`);
+        }
+        if (!name) {
+            name = arg.trim();
+            if (!tappId) {
+                tappId = normalizeProjectValue(name, "tapp");
+            }
+            continue;
+        }
+        throw new Error(`Unexpected tapp create argument: ${arg}`);
+    }
+    if (!tappId) {
+        throw new Error("tapp create requires a Tapp id or name.");
+    }
+    if (!name) {
+        name = tappId;
+    }
+    return {
+        apiBaseUrl: normalizeHttpUrl(apiBaseUrl, "Tapi API base URL"),
+        tappId,
+        name,
+    };
+}
+async function createTapp(args) {
+    try {
+        const options = await withSdkAuth(parseTappCreateOptions(args));
+        const tapp = await withCliSpinner(`Creating Tapi Tapp ${options.tappId}`, () => postTappCreate(options));
+        console.log(JSON.stringify(tapp, null, 2));
+        return 0;
+    }
+    catch (error) {
+        console.error(formatError(error));
+        return 1;
+    }
+}
+async function postTappCreate(options, fetchImpl = fetch) {
+    const response = await fetchImpl(`${options.apiBaseUrl.replace(/\/+$/, "")}/api/sdk/v1/tapps`, {
+        method: "POST",
+        headers: sdkJsonHeaders(options.authToken, options.tappId),
+        body: JSON.stringify({
+            tappId: options.tappId,
+            name: options.name,
+        }),
+    });
+    const body = await readJsonBody(response);
+    if (!response.ok) {
+        const detail = body?.detail ?? body?.error ?? body ?? `HTTP ${response.status}`;
+        throw new Error(typeof detail === "string" ? detail : JSON.stringify(detail));
+    }
+    return body ?? {};
+}
+async function addTappService(args) {
+    try {
+        const options = await withSdkAuth(parseTappServiceAddOptions(args));
+        const operation = await withCliSpinner(`Adding Tapi service ${options.serviceCall} to ${options.tappId}`, () => postTappServiceAdd(options));
+        console.log(JSON.stringify(operation, null, 2));
+        return 0;
+    }
+    catch (error) {
+        console.error(formatError(error));
+        return 1;
+    }
+}
+async function postTappServiceAdd(options) {
+    const response = await fetch(`${options.apiBaseUrl.replace(/\/+$/, "")}/api/sdk/v1/tapps/${encodeURIComponent(options.tappId)}/services/${encodeURIComponent(options.serviceCall)}`, {
+        method: "POST",
+        headers: sdkJsonHeaders(options.authToken, options.tappId),
+        body: JSON.stringify({
+            serviceMapId: options.serviceMapId,
+            entry: options.entry,
+            ...(options.expectedRevision ? { expectedRevision: options.expectedRevision } : {}),
+        }),
+    });
+    const body = await readJsonBody(response);
+    if (!response.ok) {
+        const detail = body?.detail ?? body?.error ?? body ?? `HTTP ${response.status}`;
+        throw new Error(typeof detail === "string" ? detail : JSON.stringify(detail));
+    }
+    return body ?? {};
+}
+function parseQueueCreateOptions(args) {
+    const workspace = loadWorkspace();
+    let apiBaseUrl = envString("TAPI_BASE_URL") || workspace?.apiBaseUrl || DEFAULT_STUDIO_API_BASE_URL;
+    let projectId = envString("TAPI_PROJECT_ID") || workspace?.projectId || "";
+    let displayName = "";
+    let maxSlots = 8;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!arg)
+            continue;
+        if (arg === "--api-base-url" || arg === "--server") {
+            apiBaseUrl = requireOptionValue(args, ++index, arg);
+            continue;
+        }
+        if (arg.startsWith("--api-base-url=")) {
+            apiBaseUrl = arg.slice("--api-base-url=".length);
+            continue;
+        }
+        if (arg.startsWith("--server=")) {
+            apiBaseUrl = arg.slice("--server=".length);
+            continue;
+        }
+        if (arg === "--project") {
+            projectId = normalizeProjectValue(requireOptionValue(args, ++index, "--project"), "project");
+            continue;
+        }
+        if (arg.startsWith("--project=")) {
+            projectId = normalizeProjectValue(arg.slice("--project=".length), "project");
+            continue;
+        }
+        if (arg === "--max-slots") {
+            maxSlots = parsePositiveInteger(requireOptionValue(args, ++index, "--max-slots"), "--max-slots");
+            continue;
+        }
+        if (arg.startsWith("--max-slots=")) {
+            maxSlots = parsePositiveInteger(arg.slice("--max-slots=".length), "--max-slots");
+            continue;
+        }
+        if (arg.startsWith("--")) {
+            throw new Error(`Unknown queue create option: ${arg}`);
+        }
+        if (!displayName) {
+            displayName = arg.trim();
+            continue;
+        }
+        throw new Error(`Unexpected queue create argument: ${arg}`);
+    }
+    return {
+        apiBaseUrl: normalizeHttpUrl(apiBaseUrl, "Tapi API base URL"),
+        projectId,
+        displayName,
+        maxSlots,
     };
 }
-function parseServiceOptions(args) {
-    let operation = "";
+function parseTappQueueAddOptions(args) {
     const workspace = loadWorkspace();
     let apiBaseUrl = envString("TAPI_BASE_URL") || workspace?.apiBaseUrl || DEFAULT_STUDIO_API_BASE_URL;
-    let apiKey = envString("TAPI_API_KEY") || "";
-    let projectId = envString("TAPI_PROJECT_ID") || workspace?.projectId || "";
+    let tappId = "";
+    let queueId = "";
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (!arg)
@@ -389,12 +894,52 @@ function parseServiceOptions(args) {
             apiBaseUrl = arg.slice("--server=".length);
             continue;
         }
-        if (arg === "--api-key") {
-            apiKey = requireOptionValue(args, ++index, "--api-key");
+        if (arg.startsWith("--")) {
+            throw new Error(`Unknown tapp queue add option: ${arg}`);
+        }
+        if (!tappId) {
+            tappId = normalizeProjectValue(arg, "tapp");
+            continue;
+        }
+        if (!queueId) {
+            queueId = arg.trim();
+            continue;
+        }
+        throw new Error(`Unexpected tapp queue add argument: ${arg}`);
+    }
+    if (!tappId) {
+        throw new Error("tapp queue add requires a Tapp id.");
+    }
+    if (!queueId) {
+        throw new Error("tapp queue add requires a queue id.");
+    }
+    return {
+        apiBaseUrl: normalizeHttpUrl(apiBaseUrl, "Tapi API base URL"),
+        tappId,
+        queueId,
+    };
+}
+function parseRunnerSlotSetOptions(args) {
+    const workspace = loadWorkspace();
+    let apiBaseUrl = envString("TAPI_BASE_URL") || workspace?.apiBaseUrl || DEFAULT_STUDIO_API_BASE_URL;
+    let projectId = envString("TAPI_PROJECT_ID") || workspace?.projectId || "";
+    let runnerId = "";
+    let slotIndex = 0;
+    let queueId = "";
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!arg)
+            continue;
+        if (arg === "--api-base-url" || arg === "--server") {
+            apiBaseUrl = requireOptionValue(args, ++index, arg);
+            continue;
+        }
+        if (arg.startsWith("--api-base-url=")) {
+            apiBaseUrl = arg.slice("--api-base-url=".length);
             continue;
         }
-        if (arg.startsWith("--api-key=")) {
-            apiKey = arg.slice("--api-key=".length);
+        if (arg.startsWith("--server=")) {
+            apiBaseUrl = arg.slice("--server=".length);
             continue;
         }
         if (arg === "--project") {
@@ -406,42 +951,47 @@ function parseServiceOptions(args) {
             continue;
         }
         if (arg.startsWith("--")) {
-            throw new Error(`Unknown services option: ${arg}`);
+            throw new Error(`Unknown runner slot set option: ${arg}`);
         }
-        if (!operation) {
-            operation = arg;
+        if (!runnerId) {
+            runnerId = arg.trim();
             continue;
         }
-        throw new Error(`Unexpected services argument: ${arg}`);
+        if (!slotIndex) {
+            slotIndex = parsePositiveInteger(arg.trim(), "slot index");
+            continue;
+        }
+        if (!queueId) {
+            queueId = arg.trim();
+            continue;
+        }
+        throw new Error(`Unexpected runner slot set argument: ${arg}`);
     }
-    if (!operation) {
-        throw new Error("services describe requires a service run like schwab.place_order.");
+    if (!projectId) {
+        throw new Error("runner slot set requires --project or TAPI_PROJECT_ID.");
     }
-    if (!apiKey) {
-        throw new Error("services describe requires --api-key or TAPI_API_KEY.");
+    if (!runnerId) {
+        throw new Error("runner slot set requires a runner id.");
     }
-    if (!projectId) {
-        throw new Error("services describe requires --project, TAPI_PROJECT_ID, or .tapi/project.json.");
+    if (!slotIndex) {
+        throw new Error("runner slot set requires a slot index.");
+    }
+    if (!queueId) {
+        throw new Error("runner slot set requires a queue id.");
     }
     return {
-        operation,
-        options: {
-            apiBaseUrl: normalizeHttpUrl(apiBaseUrl, "Tapi API base URL"),
-            apiKey,
-            projectId,
-        },
+        apiBaseUrl: normalizeHttpUrl(apiBaseUrl, "Tapi API base URL"),
+        projectId,
+        runnerId,
+        slotIndex,
+        queueId,
     };
 }
-async function describeServiceOperation(args) {
+async function createQueue(args) {
     try {
-        const { operation, options } = parseServiceOptions(args);
-        const client = new TapiClient({
-            baseUrl: options.apiBaseUrl,
-            apiKey: options.apiKey,
-            projectId: options.projectId,
-        });
-        const description = await withCliSpinner(`Fetching Tapi service-run contract for ${operation}`, () => client.services.describe(operation));
-        console.log(JSON.stringify(description, null, 2));
+        const options = await withSdkAuth(parseQueueCreateOptions(args));
+        const queue = await withCliSpinner(`Creating Tapi queue`, () => postQueueCreate(options));
+        console.log(JSON.stringify(queue, null, 2));
         return 0;
     }
     catch (error) {
@@ -449,13 +999,80 @@ async function describeServiceOperation(args) {
         return 1;
     }
 }
-function parseApiWorkspaceOptions(args) {
+async function addTappQueue(args) {
+    try {
+        const options = await withSdkAuth(parseTappQueueAddOptions(args));
+        const result = await withCliSpinner(`Attaching Tapi queue ${options.queueId} to ${options.tappId}`, () => postTappQueueAdd(options));
+        console.log(JSON.stringify(result, null, 2));
+        return 0;
+    }
+    catch (error) {
+        console.error(formatError(error));
+        return 1;
+    }
+}
+async function setRunnerSlot(args) {
+    try {
+        const options = await withSdkAuth(parseRunnerSlotSetOptions(args));
+        const result = await withCliSpinner(`Assigning runner slot ${options.runnerId}/${options.slotIndex} to queue ${options.queueId}`, () => putRunnerSlot(options));
+        console.log(JSON.stringify(result, null, 2));
+        return 0;
+    }
+    catch (error) {
+        console.error(formatError(error));
+        return 1;
+    }
+}
+async function postQueueCreate(options) {
+    const headers = sdkJsonHeaders(options.authToken, options.projectId);
+    const response = await fetch(`${options.apiBaseUrl.replace(/\/+$/, "")}/api/sdk/v1/queues`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+            ...(options.displayName ? { displayName: options.displayName } : {}),
+            maxSlots: options.maxSlots,
+        }),
+    });
+    const body = await readJsonBody(response);
+    if (!response.ok) {
+        const detail = body?.detail ?? body?.error ?? body ?? `HTTP ${response.status}`;
+        throw new Error(typeof detail === "string" ? detail : JSON.stringify(detail));
+    }
+    return body ?? {};
+}
+async function postTappQueueAdd(options) {
+    const response = await fetch(`${options.apiBaseUrl.replace(/\/+$/, "")}/api/sdk/v1/tapps/${encodeURIComponent(options.tappId)}/queues`, {
+        method: "POST",
+        headers: sdkJsonHeaders(options.authToken, options.tappId),
+        body: JSON.stringify({ queueId: options.queueId }),
+    });
+    const body = await readJsonBody(response);
+    if (!response.ok) {
+        const detail = body?.detail ?? body?.error ?? body ?? `HTTP ${response.status}`;
+        throw new Error(typeof detail === "string" ? detail : JSON.stringify(detail));
+    }
+    return body ?? {};
+}
+async function putRunnerSlot(options) {
+    const response = await fetch(`${options.apiBaseUrl.replace(/\/+$/, "")}/api/sdk/v1/runners/${encodeURIComponent(options.runnerId)}/slots/${encodeURIComponent(String(options.slotIndex))}`, {
+        method: "PUT",
+        headers: sdkJsonHeaders(options.authToken, options.projectId),
+        body: JSON.stringify({ queueId: options.queueId }),
+    });
+    const body = await readJsonBody(response);
+    if (!response.ok) {
+        const detail = body?.detail ?? body?.error ?? body ?? `HTTP ${response.status}`;
+        throw new Error(typeof detail === "string" ? detail : JSON.stringify(detail));
+    }
+    return body ?? {};
+}
+export function parseRunnerSetupOptions(args) {
     const workspace = loadWorkspace();
     let apiBaseUrl = envString("TAPI_BASE_URL") || workspace?.apiBaseUrl || DEFAULT_STUDIO_API_BASE_URL;
-    let apiKey = envString("TAPI_API_KEY") || "";
     let projectId = envString("TAPI_PROJECT_ID") || workspace?.projectId || "";
-    let catalogPath = workspace?.config.services?.catalog || workspace?.config.generated?.catalog || ".tapi/services/catalog.json";
-    let typescriptPath = workspace?.config.services?.typescript || workspace?.config.generated?.typescript || "src/tapi.services.ts";
+    let runnerId = envString("TAPI_RUNNER_ID") || "";
+    let port = Number(envString("TAPI_RUNNER_SETUP_PORT") || "17687");
+    let openBrowser = true;
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (!arg)
@@ -472,14 +1089,6 @@ function parseApiWorkspaceOptions(args) {
             apiBaseUrl = arg.slice("--server=".length);
             continue;
         }
-        if (arg === "--api-key") {
-            apiKey = requireOptionValue(args, ++index, "--api-key");
-            continue;
-        }
-        if (arg.startsWith("--api-key=")) {
-            apiKey = arg.slice("--api-key=".length);
-            continue;
-        }
         if (arg === "--project") {
             projectId = normalizeProjectValue(requireOptionValue(args, ++index, "--project"), "project");
             continue;
@@ -488,45 +1097,63 @@ function parseApiWorkspaceOptions(args) {
             projectId = normalizeProjectValue(arg.slice("--project=".length), "project");
             continue;
         }
-        if (arg === "--catalog") {
-            catalogPath = requireOptionValue(args, ++index, "--catalog");
+        if (arg === "--runner-id") {
+            runnerId = requireOptionValue(args, ++index, "--runner-id").trim();
             continue;
         }
-        if (arg.startsWith("--catalog=")) {
-            catalogPath = arg.slice("--catalog=".length);
+        if (arg.startsWith("--runner-id=")) {
+            runnerId = arg.slice("--runner-id=".length).trim();
             continue;
         }
-        if (arg === "--out") {
-            typescriptPath = requireOptionValue(args, ++index, "--out");
+        if (arg === "--port") {
+            port = parseNonNegativeInteger(requireOptionValue(args, ++index, "--port"), "--port");
             continue;
         }
-        if (arg.startsWith("--out=")) {
-            typescriptPath = arg.slice("--out=".length);
+        if (arg.startsWith("--port=")) {
+            port = parseNonNegativeInteger(arg.slice("--port=".length), "--port");
             continue;
         }
-        throw new Error(`Unknown services option: ${arg}`);
-    }
-    if (!apiKey) {
-        throw new Error("services command requires --api-key or TAPI_API_KEY.");
+        if (arg === "--no-open") {
+            openBrowser = false;
+            continue;
+        }
+        if (arg.startsWith("--")) {
+            throw new Error(`Unknown runner setup option: ${arg}`);
+        }
+        if (!runnerId) {
+            runnerId = arg.trim();
+            continue;
+        }
+        throw new Error(`Unexpected runner setup argument: ${arg}`);
     }
     if (!projectId) {
-        throw new Error("services command requires --project, TAPI_PROJECT_ID, or .tapi/project.json.");
+        throw new Error("runner setup requires --project or TAPI_PROJECT_ID.");
+    }
+    if (!runnerId) {
+        throw new Error("runner setup requires --runner-id or TAPI_RUNNER_ID.");
+    }
+    if (!Number.isInteger(port) || port < 0) {
+        throw new Error("--port must be a non-negative integer.");
     }
-    const root = workspace?.root || process.cwd();
     return {
         apiBaseUrl: normalizeHttpUrl(apiBaseUrl, "Tapi API base URL"),
-        apiKey,
         projectId,
-        catalogPath: resolve(root, catalogPath),
-        typescriptPath: resolve(root, typescriptPath),
+        runnerId,
+        port,
+        openBrowser,
     };
 }
-async function syncServiceCatalog(args) {
+async function runRunnerSetup(args) {
     try {
-        const options = parseApiWorkspaceOptions(args);
-        const catalog = await withCliSpinner("Fetching Tapi service-run catalog", () => fetchApiCatalog(options));
-        await writeJsonFile(options.catalogPath, catalog);
-        console.log(`Synced Tapi service-run catalog: ${options.catalogPath}`);
+        const options = await withSdkAuth(parseRunnerSetupOptions(args));
+        const handle = await startRunnerSetupServer(options);
+        if (options.openBrowser) {
+            openUrlInBrowser(handle.url);
+        }
+        console.log(`Tapi runner setup: ${handle.url}`);
+        console.log("Press Ctrl+C to stop the setup server.");
+        await waitForProcessSignal();
+        await handle.close();
         return 0;
     }
     catch (error) {
@@ -534,24 +1161,230 @@ async function syncServiceCatalog(args) {
         return 1;
     }
 }
-async function generateServiceClient(args) {
+export async function startRunnerSetupServer(options, fetchImpl = fetch) {
+    const server = createServer((request, response) => {
+        void handleRunnerSetupRequest(request, response, options, fetchImpl);
+    });
+    await listenOnLocalhost(server, options.port);
+    const address = server.address();
+    const port = typeof address === "object" && address ? address.port : options.port;
+    return {
+        url: `http://127.0.0.1:${port}/`,
+        port,
+        close: () => closeServer(server),
+    };
+}
+export async function executeRunnerSetupAction(options, action, fetchImpl = fetch) {
+    let queueId = String(action.queueId || "").trim();
+    const maxSlots = coercePositiveInteger(action.maxSlots, 8, "maxSlots");
+    const slotStart = coercePositiveInteger(action.slotStart, 1, "slotStart");
+    const slotCount = coercePositiveInteger(action.slotCount, 1, "slotCount");
+    let queue = {};
+    if (!queueId) {
+        queue = await sdkJsonRequest(fetchImpl, `${options.apiBaseUrl.replace(/\/+$/, "")}/api/sdk/v1/queues`, {
+            method: "POST",
+            headers: sdkJsonHeaders(options.authToken, options.projectId),
+            body: JSON.stringify({
+                displayName: String(action.displayName || `${options.projectId} queue`).trim(),
+                maxSlots,
+            }),
+        });
+        queueId = String(queue.queueId || queue.queue_id || "").trim();
+    }
+    if (!queueId) {
+        throw new Error("Runner setup needs an existing queue id or a created queue response with queueId.");
+    }
+    const attachment = await sdkJsonRequest(fetchImpl, `${options.apiBaseUrl.replace(/\/+$/, "")}/api/sdk/v1/tapps/${encodeURIComponent(options.projectId)}/queues`, {
+        method: "POST",
+        headers: sdkJsonHeaders(options.authToken, options.projectId),
+        body: JSON.stringify({ queueId }),
+    });
+    const slots = [];
+    for (let offset = 0; offset < slotCount; offset += 1) {
+        const slotIndex = slotStart + offset;
+        slots.push(await sdkJsonRequest(fetchImpl, `${options.apiBaseUrl.replace(/\/+$/, "")}/api/sdk/v1/runners/${encodeURIComponent(options.runnerId)}/slots/${encodeURIComponent(String(slotIndex))}`, {
+            method: "PUT",
+            headers: sdkJsonHeaders(options.authToken, options.projectId),
+            body: JSON.stringify({ queueId }),
+        }));
+    }
+    return {
+        queueId,
+        queue: queueId && !Object.keys(queue).length ? { queueId } : queue,
+        attachment,
+        slots,
+    };
+}
+async function handleRunnerSetupRequest(request, response, options, fetchImpl) {
     try {
-        const options = parseApiWorkspaceOptions(args);
-        const catalog = await withCliSpinner("Fetching Tapi service-run catalog", () => fetchApiCatalog(options));
-        await writeJsonFile(options.catalogPath, catalog);
-        await writeTextFile(options.typescriptPath, renderServiceRunClient(catalog));
-        console.log(`Wrote Tapi service-run client: ${options.typescriptPath}`);
-        return 0;
+        const url = new URL(request.url || "/", "http://127.0.0.1");
+        if (request.method === "GET" && url.pathname === "/") {
+            sendText(response, 200, runnerSetupHtml(options), "text/html; charset=utf-8");
+            return;
+        }
+        if (request.method === "GET" && url.pathname === "/api/status") {
+            sendJson(response, 200, {
+                apiBaseUrl: options.apiBaseUrl,
+                projectId: options.projectId,
+                runnerId: options.runnerId,
+            });
+            return;
+        }
+        if (request.method === "POST" && url.pathname === "/api/setup") {
+            const body = await readRequestJson(request);
+            const result = await executeRunnerSetupAction(options, body, fetchImpl);
+            sendJson(response, 200, result);
+            return;
+        }
+        sendJson(response, 404, { error: "not found" });
     }
     catch (error) {
-        console.error(formatError(error));
-        return 1;
+        sendJson(response, 400, { error: formatError(error) });
+    }
+}
+function runnerSetupHtml(options) {
+    const displayName = `${options.projectId} queue`;
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Tapi Runner Setup</title>
+<style>
+:root { color-scheme: light dark; --bg: #f7f7f5; --panel: #ffffff; --text: #1d2329; --muted: #62707c; --line: #d6dde2; --accent: #176b4d; --accent-2: #0f5ca8; --danger: #ad2e24; }
+@media (prefers-color-scheme: dark) { :root { --bg: #111418; --panel: #181d22; --text: #eef3f6; --muted: #a6b1bb; --line: #303a43; --accent: #59b88c; --accent-2: #6da8e8; --danger: #ee786e; } }
+* { box-sizing: border-box; }
+body { margin: 0; font: 14px/1.45 system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; color: var(--text); background: var(--bg); }
+main { max-width: 920px; margin: 0 auto; padding: 28px 18px 36px; }
+h1 { margin: 0 0 18px; font-size: 28px; font-weight: 650; letter-spacing: 0; }
+h2 { margin: 0 0 12px; font-size: 16px; font-weight: 650; letter-spacing: 0; }
+.grid { display: grid; grid-template-columns: minmax(0, 1fr) minmax(260px, 320px); gap: 18px; align-items: start; }
+.panel, .summary { background: var(--panel); border: 1px solid var(--line); border-radius: 8px; padding: 18px; }
+.row { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 12px; }
+label { display: grid; gap: 6px; margin: 0 0 12px; color: var(--muted); font-size: 12px; font-weight: 600; text-transform: uppercase; }
+input { width: 100%; min-width: 0; border: 1px solid var(--line); border-radius: 6px; padding: 10px 11px; color: var(--text); background: transparent; font: inherit; }
+button { border: 0; border-radius: 6px; padding: 11px 14px; color: white; background: var(--accent); font: inherit; font-weight: 650; cursor: pointer; }
+button:disabled { opacity: .55; cursor: progress; }
+code { word-break: break-all; }
+.summary dl { display: grid; grid-template-columns: 88px minmax(0, 1fr); gap: 8px 10px; margin: 0; }
+.summary dt { color: var(--muted); font-weight: 650; }
+.summary dd { margin: 0; min-width: 0; }
+.result { margin-top: 14px; min-height: 120px; border: 1px solid var(--line); border-radius: 8px; padding: 12px; overflow: auto; background: rgba(0,0,0,.035); white-space: pre-wrap; }
+.error { color: var(--danger); }
+.ok { color: var(--accent-2); }
+@media (max-width: 720px) { .grid, .row { grid-template-columns: 1fr; } main { padding: 20px 14px 28px; } h1 { font-size: 24px; } }
+</style>
+</head>
+<body>
+<main>
+<h1>Tapi Runner Setup</h1>
+<div class="grid">
+<section class="panel">
+<h2>Queue And Slots</h2>
+<form id="setup-form">
+<label>Existing Queue ID<input id="queueId" name="queueId" autocomplete="off" placeholder="queue_abc123"></label>
+<label>New Queue Name<input id="displayName" name="displayName" value="${escapeHtml(displayName)}" autocomplete="off"></label>
+<div class="row">
+<label>Queue Slot Limit<input id="maxSlots" name="maxSlots" type="number" min="1" step="1" value="8"></label>
+<label>First Runner Slot<input id="slotStart" name="slotStart" type="number" min="1" step="1" value="1"></label>
+</div>
+<label>Runner Slot Count<input id="slotCount" name="slotCount" type="number" min="1" step="1" value="1"></label>
+<button id="submit" type="submit">Apply Setup</button>
+</form>
+<pre id="result" class="result" aria-live="polite"></pre>
+</section>
+<aside class="summary">
+<h2>Target</h2>
+<dl>
+<dt>Server</dt><dd><code>${escapeHtml(options.apiBaseUrl)}</code></dd>
+<dt>Tapp</dt><dd><code>${escapeHtml(options.projectId)}</code></dd>
+<dt>Runner</dt><dd><code>${escapeHtml(options.runnerId)}</code></dd>
+</dl>
+</aside>
+</div>
+</main>
+<script>
+const form = document.getElementById("setup-form");
+const button = document.getElementById("submit");
+const result = document.getElementById("result");
+form.addEventListener("submit", async (event) => {
+  event.preventDefault();
+  button.disabled = true;
+  result.className = "result";
+  result.textContent = "Applying setup...";
+  const body = Object.fromEntries(new FormData(form).entries());
+  body.maxSlots = Number(body.maxSlots || 8);
+  body.slotStart = Number(body.slotStart || 1);
+  body.slotCount = Number(body.slotCount || 1);
+  try {
+    const response = await fetch("/api/setup", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    const payload = await response.json();
+    if (!response.ok) throw new Error(payload.error || JSON.stringify(payload));
+    result.className = "result ok";
+    result.textContent = JSON.stringify(payload, null, 2);
+    document.getElementById("queueId").value = payload.queueId || body.queueId || "";
+  } catch (error) {
+    result.className = "result error";
+    result.textContent = error instanceof Error ? error.message : String(error);
+  } finally {
+    button.disabled = false;
+  }
+});
+</script>
+</body>
+</html>`;
+}
+async function sdkJsonRequest(fetchImpl, url, init) {
+    const response = await fetchImpl(url, init);
+    const body = await readJsonBody(response);
+    if (!response.ok) {
+        const detail = body?.detail ?? body?.error ?? body ?? `HTTP ${response.status}`;
+        throw new Error(typeof detail === "string" ? detail : JSON.stringify(detail));
+    }
+    return body ?? {};
+}
+function sdkJsonHeaders(authToken, projectId) {
+    const headers = {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${requireSdkAuthToken(authToken)}`,
+    };
+    if (projectId) {
+        headers["X-Tapi-Project"] = projectId;
+    }
+    return headers;
+}
+function requireSdkAuthToken(authToken) {
+    const normalized = String(authToken || "").trim();
+    if (!normalized) {
+        throw new Error("Tapi sign-in is required. Run `tapi login`, then retry.");
+    }
+    return normalized;
+}
+function coercePositiveInteger(value, fallback, label) {
+    const text = value === undefined || value === null || value === "" ? String(fallback) : String(value);
+    return parsePositiveInteger(text, label);
+}
+function parsePositiveInteger(value, label) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+        throw new Error(`${label} must be a positive integer.`);
+    }
+    return parsed;
+}
+function parseNonNegativeInteger(value, label) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        throw new Error(`${label} must be a non-negative integer.`);
     }
+    return parsed;
 }
 function parseTriggerSyncOptions(args) {
     const workspace = loadWorkspace();
     let apiBaseUrl = envString("TAPI_BASE_URL") || workspace?.apiBaseUrl || DEFAULT_STUDIO_API_BASE_URL;
-    let apiKey = envString("TAPI_API_KEY") || "";
     let projectId = envString("TAPI_PROJECT_ID") || workspace?.projectId || "";
     let configPath = "";
     const root = workspace?.root || process.cwd();
@@ -571,14 +1404,6 @@ function parseTriggerSyncOptions(args) {
             apiBaseUrl = arg.slice("--server=".length);
             continue;
         }
-        if (arg === "--api-key") {
-            apiKey = requireOptionValue(args, ++index, "--api-key");
-            continue;
-        }
-        if (arg.startsWith("--api-key=")) {
-            apiKey = arg.slice("--api-key=".length);
-            continue;
-        }
         if (arg === "--project") {
             projectId = normalizeProjectValue(requireOptionValue(args, ++index, "--project"), "project");
             continue;
@@ -597,29 +1422,26 @@ function parseTriggerSyncOptions(args) {
         }
         throw new Error(`Unknown triggers option: ${arg}`);
     }
-    if (!apiKey) {
-        throw new Error("triggers sync requires --api-key or TAPI_API_KEY.");
-    }
     if (!projectId) {
         throw new Error("triggers sync requires --project, TAPI_PROJECT_ID, or .tapi/project.json.");
     }
     return {
         apiBaseUrl: normalizeHttpUrl(apiBaseUrl, "Tapi API base URL"),
-        apiKey,
         projectId,
         configPath: configPath ? resolve(root, configPath) : defaultTriggerConfigPath(root),
     };
 }
-async function syncApiTriggers(args) {
+async function syncServiceTriggers(args) {
     try {
-        const options = parseTriggerSyncOptions(args);
-        const triggers = await readApiTriggerConfig(options.configPath);
+        const options = await withSdkAuth(parseTriggerSyncOptions(args));
+        const triggers = await readServiceTriggerConfig(options.configPath);
         if (triggers.length === 0) {
             throw new Error(`No Tapi service triggers found in ${options.configPath}.`);
         }
         const client = new TapiClient({
             baseUrl: options.apiBaseUrl,
-            apiKey: options.apiKey,
+            authToken: options.authToken,
+            tappId: options.projectId,
             projectId: options.projectId,
         });
         await withCliSpinner(`Syncing ${triggers.length} Tapi service trigger(s)`, async () => {
@@ -638,7 +1460,6 @@ async function syncApiTriggers(args) {
 function parseSessionsOptions(args) {
     const workspace = loadWorkspace();
     let apiBaseUrl = envString("TAPI_BASE_URL") || workspace?.apiBaseUrl || DEFAULT_STUDIO_API_BASE_URL;
-    let apiKey = envString("TAPI_API_KEY") || "";
     let projectId = envString("TAPI_PROJECT_ID") || workspace?.projectId || "";
     let site = "";
     let sessionId = "";
@@ -660,14 +1481,6 @@ function parseSessionsOptions(args) {
             apiBaseUrl = arg.slice("--server=".length);
             continue;
         }
-        if (arg === "--api-key") {
-            apiKey = requireOptionValue(args, ++index, "--api-key");
-            continue;
-        }
-        if (arg.startsWith("--api-key=")) {
-            apiKey = arg.slice("--api-key=".length);
-            continue;
-        }
         if (arg === "--project") {
             projectId = normalizeProjectValue(requireOptionValue(args, ++index, "--project"), "project");
             continue;
@@ -702,9 +1515,6 @@ function parseSessionsOptions(args) {
         }
         throw new Error(`Unexpected sessions argument: ${arg}`);
     }
-    if (!apiKey) {
-        throw new Error("sessions command requires --api-key or TAPI_API_KEY.");
-    }
     if (!projectId) {
         throw new Error("sessions command requires --project, TAPI_PROJECT_ID, or .tapi/project.json.");
     }
@@ -712,7 +1522,6 @@ function parseSessionsOptions(args) {
         sessionId,
         options: {
             apiBaseUrl: normalizeHttpUrl(apiBaseUrl, "Tapi API base URL"),
-            apiKey,
             projectId,
             site: site || undefined,
             json,
@@ -723,18 +1532,19 @@ function parseSessionsOptions(args) {
 async function listDevSessions(args) {
     try {
         const { options } = parseSessionsOptions(args);
-        const sessions = await fetchDevSessions(options);
-        if (options.json) {
+        const authenticated = await withSdkAuth(options);
+        const sessions = await fetchDevSessions(authenticated);
+        if (authenticated.json) {
             console.log(JSON.stringify(sessions, null, 2));
             return 0;
         }
         const rows = flattenDevSessions(sessions);
         if (rows.length === 0) {
-            console.log(`No Tapi dev sessions found for project ${sessions.projectId || options.projectId}.`);
+            console.log(`No Tapi dev sessions found for project ${sessions.projectId || authenticated.projectId}.`);
             return 0;
         }
-        if (!options.noInteractive && process.stdin.isTTY && process.stdout.isTTY && rows.some((session) => session.openable)) {
-            return await runSessionsPicker(sessions, options);
+        if (!authenticated.noInteractive && process.stdin.isTTY && process.stdout.isTTY && rows.some((session) => session.openable)) {
+            return await runSessionsPicker(sessions, authenticated);
         }
         console.log(renderDevSessions(sessions));
         const openable = rows.find((session) => session.openable);
@@ -751,15 +1561,16 @@ async function listDevSessions(args) {
 async function openDevSession(args) {
     try {
         const { sessionId, options } = parseSessionsOptions(args);
+        const authenticated = await withSdkAuth(options);
         if (!sessionId) {
             throw new Error("sessions open requires a session id.");
         }
-        const sessions = await fetchDevSessions(options);
+        const sessions = await fetchDevSessions(authenticated);
         const session = findDevSession(sessions, sessionId);
         if (!session) {
             throw new Error(`Tapi session not found: ${sessionId}`);
         }
-        return await openDevSessionInStudio(session, options);
+        return await openDevSessionInStudio(session, authenticated);
     }
     catch (error) {
         console.error(formatError(error));
@@ -769,7 +1580,8 @@ async function openDevSession(args) {
 async function fetchDevSessions(options) {
     const client = new TapiClient({
         baseUrl: options.apiBaseUrl,
-        apiKey: options.apiKey,
+        authToken: options.authToken,
+        tappId: options.projectId,
         projectId: options.projectId,
     });
     return await withCliSpinner("Fetching Tapi dev sessions", () => client.sessions.list({ site: options.site }));
@@ -897,7 +1709,6 @@ async function openDevSessionInStudio(session, options) {
 function studioSessionLaunchParams(session) {
     const params = new URLSearchParams();
     params.set("runId", session.id);
-    params.set("apiRunId", session.id);
     if (session.sitemap)
         params.set("sitemap", session.sitemap);
     if (session.runtimeSessionId)
@@ -908,7 +1719,6 @@ function studioSessionSelectIntent(session) {
     return {
         sessionId: session.id,
         runId: session.id,
-        apiRunId: session.id,
         ...(session.sitemap ? { sitemap: session.sitemap } : {}),
         ...(session.runtimeSessionId ? { runtimeSessionId: session.runtimeSessionId } : {}),
         source: "cli",
@@ -961,12 +1771,12 @@ function renderDevSessions(sessions, selectedId = "") {
             const openable = session.openable ? "*" : " ";
             const id = truncateText(session.id || "", 18).padEnd(18, " ");
             const status = truncateText(String(session.status || ""), 24).padEnd(24, " ");
-            const apiName = session.apiName && session.requestKey
-                ? `${session.apiName}.${session.requestKey}`
-                : session.apiName || session.requestKey || "unknown";
+            const serviceRun = session.serviceRun || (session.serviceName && session.serviceKey
+                ? `${session.serviceName}.${session.serviceKey}`
+                : session.serviceName || session.serviceKey || "unknown");
             const state = session.stateLabel ? ` state=${session.stateLabel}` : "";
             const url = session.currentUrl ? ` ${truncateText(session.currentUrl, 60)}` : "";
-            lines.push(`${selected}${openable} ${id} ${status} ${apiName}${state}${url}`);
+            lines.push(`${selected}${openable} ${id} ${status} ${serviceRun}${state}${url}`);
         }
     }
     lines.push("");
@@ -988,7 +1798,7 @@ function defaultTriggerConfigPath(root) {
     }
     return join(root, "tapi.config.json");
 }
-async function readApiTriggerConfig(configPath) {
+async function readServiceTriggerConfig(configPath) {
     if (!existsSync(configPath)) {
         throw new Error(`Tapi trigger config not found at ${configPath}. Create tapi.config.json or pass --config.`);
     }
@@ -1051,26 +1861,31 @@ function normalizeTriggerEntry(entry, index, configPath) {
         throw new Error(`Trigger #${index + 1} in ${configPath} must be an object.`);
     }
     const name = stringField(entry.name, `Trigger #${index + 1} name`);
-    const serviceRun = optionalStringField(entry.serviceRun, "serviceRun") ??
-        optionalStringField(entry.service, "service") ??
-        optionalStringField(entry.apiRequest, "apiRequest") ??
-        optionalStringField(entry.api, "api") ??
-        serviceRunFromParts(entry.serviceName ?? entry.apiName, entry.requestKey);
+    if (RETIRED_TRIGGER_TARGET_FIELD in entry) {
+        throw new Error(`Trigger '${name}' uses a retired trigger target field; use serviceRun.`);
+    }
+    const serviceRun = optionalStringField(entry.serviceRun, "serviceRun");
     if (!serviceRun) {
-        throw new Error(`Trigger '${name}' requires serviceRun, service, or serviceName/requestKey.`);
+        throw new Error(`Trigger '${name}' requires serviceRun.`);
     }
     if (!serviceRun.includes(".")) {
-        throw new Error(`Trigger '${name}' serviceRun must be formatted as '<serviceName>.<requestKey>'.`);
+        throw new Error(`Trigger '${name}' serviceRun must be formatted as '<serviceName>.<serviceKey>'.`);
+    }
+    if ("runnerId" in entry) {
+        throw new Error(`Trigger '${name}' uses runnerId; use queueId.`);
     }
     const schedule = normalizeTriggerSchedule(entry.schedule, entry.interval, name);
+    const runtime = entry.runtime === undefined ? undefined : recordField(entry.runtime, `Trigger '${name}' runtime`);
+    rejectNonPolicyTriggerRuntimeOwner(runtime, `Trigger '${name}' runtime`);
+    const queueId = stringField(entry.queueId, `Trigger '${name}' queueId`);
     const request = {
         name,
-        apiRequest: serviceRun,
+        serviceRun,
+        queueId,
         ...(entry.enabled === undefined ? {} : { enabled: booleanField(entry.enabled, `Trigger '${name}' enabled`) }),
         ...(schedule ? { schedule } : {}),
         ...(entry.inputs === undefined ? {} : { inputs: recordField(entry.inputs, `Trigger '${name}' inputs`) }),
-        ...(entry.runtime === undefined ? {} : { runtime: recordField(entry.runtime, `Trigger '${name}' runtime`) }),
-        ...(entry.runnerId === undefined ? {} : { runnerId: stringField(entry.runnerId, `Trigger '${name}' runnerId`) }),
+        ...(runtime === undefined ? {} : { runtime }),
         ...(entry.priority === undefined ? {} : { priority: numberField(entry.priority, `Trigger '${name}' priority`) }),
         ...(entry.site === undefined ? {} : { site: stringField(entry.site, `Trigger '${name}' site`) }),
     };
@@ -1153,11 +1968,6 @@ function parseDurationSeconds(value, fieldName) {
     }
     return seconds;
 }
-function serviceRunFromParts(serviceName, requestKey) {
-    const api = optionalStringField(serviceName, "serviceName");
-    const request = optionalStringField(requestKey, "requestKey");
-    return api && request ? `${api}.${request}` : undefined;
-}
 function stringField(value, fieldName) {
     if (typeof value !== "string" || !value.trim()) {
         throw new Error(`${fieldName} must be a non-empty string.`);
@@ -1188,10 +1998,30 @@ function recordField(value, fieldName) {
     }
     return value;
 }
+function rejectNonPolicyTriggerRuntimeOwner(runtime, fieldName) {
+    if (!runtime) {
+        return;
+    }
+    for (const field of RETIRED_RUNTIME_OWNER_ALIAS_FIELDS) {
+        if (field in runtime) {
+            throw new Error(`unsupported service trigger runtime field: ${field}`);
+        }
+    }
+    for (const field of RUNTIME_OWNER_FIELDS) {
+        if (!(field in runtime)) {
+            continue;
+        }
+        const owner = String(runtime[field] ?? "").trim().toLowerCase();
+        if (owner && owner !== SERVICE_RUN_RUNTIME_OWNER) {
+            throw new Error(`${fieldName} owner must be service_run.`);
+        }
+    }
+}
 async function fetchApiCatalog(options) {
     const client = new TapiClient({
         baseUrl: options.apiBaseUrl,
-        apiKey: options.apiKey,
+        authToken: options.authToken,
+        tappId: options.projectId,
         projectId: options.projectId,
     });
     return client.catalog.get();
@@ -1203,50 +2033,6 @@ async function writeTextFile(path, content) {
     await mkdir(dirname(path), { recursive: true });
     await writeFile(path, content, "utf8");
 }
-function renderServiceRunClient(catalog) {
-    const namespaces = new Map();
-    for (const api of catalog.apis || []) {
-        const namespace = safeIdentifier(api.name || "api");
-        for (const request of api.requests || []) {
-            const key = String(request.operation || request.sdkName || request.key || "").trim();
-            if (!key)
-                continue;
-            const operationName = safeIdentifier(key);
-            const operation = `${api.name}.${key}`;
-            const items = namespaces.get(namespace) ?? [];
-            items.push({ key: operation, operationName });
-            namespaces.set(namespace, items);
-        }
-    }
-    const namespaceBlocks = [...namespaces.entries()].map(([namespace, operations]) => {
-        const lines = operations.map(({ key, operationName }) => `    ${operationName}: (inputs: Record<string, unknown> = {}, options: ServiceRunOptions = {}) => client.services.run(${JSON.stringify(key)}, { ...options, inputs }),`);
-        return `  ${namespace}: {\n${lines.join("\n")}\n  },`;
-    });
-    return `/* Created by Tapi. Do not edit by hand. */
-import { TapiClient, type TapiClientOptions, type RuntimeRunOptions } from "@tapi-dev/sdk";
-
-export interface ServiceRunOptions {
-  runtime?: RuntimeRunOptions;
-  priority?: number;
-  runnerId?: string;
-  idempotencyKey?: string;
-  site?: string;
-}
-
-export function createTapiServicesClient(options: TapiClientOptions) {
-  const client = new TapiClient(options);
-  return {
-${namespaceBlocks.join("\n")}
-  };
-}
-`;
-}
-function safeIdentifier(value) {
-    const cleaned = String(value || "api")
-        .replace(/[^a-zA-Z0-9_$]+/g, "_")
-        .replace(/^([^a-zA-Z_$])/, "_$1");
-    return cleaned || "api";
-}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -2994,6 +3780,56 @@ function openBrowser(url) {
     });
     child.unref();
 }
+function openUrlInBrowser(url) {
+    if (process.platform === "win32") {
+        openBrowser(url);
+        return;
+    }
+    const command = process.platform === "darwin" ? "open" : "xdg-open";
+    const child = spawn(command, [url], {
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+    });
+    child.unref();
+}
+async function listenOnLocalhost(server, port) {
+    await new Promise((resolvePromise, rejectPromise) => {
+        const onError = (error) => {
+            server.off("listening", onListening);
+            rejectPromise(error);
+        };
+        const onListening = () => {
+            server.off("error", onError);
+            resolvePromise();
+        };
+        server.once("error", onError);
+        server.once("listening", onListening);
+        server.listen(port, "127.0.0.1");
+    });
+}
+async function closeServer(server) {
+    await new Promise((resolvePromise, rejectPromise) => {
+        server.close((error) => {
+            if (error) {
+                rejectPromise(error);
+                return;
+            }
+            resolvePromise();
+        });
+    });
+}
+async function waitForProcessSignal() {
+    await new Promise((resolvePromise) => {
+        const done = () => {
+            process.off("SIGINT", done);
+            process.off("SIGTERM", done);
+            resolvePromise();
+        };
+        process.once("SIGINT", done);
+        process.once("SIGTERM", done);
+    });
+}
 async function readJsonBody(response) {
     const text = await response.text();
     if (!text.trim()) {
@@ -3006,6 +3842,40 @@ async function readJsonBody(response) {
         return null;
     }
 }
+async function readRequestJson(request) {
+    let body = "";
+    for await (const chunk of request) {
+        body += Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk);
+        if (Buffer.byteLength(body, "utf8") > 64 * 1024) {
+            throw new Error("request body is too large");
+        }
+    }
+    if (!body.trim()) {
+        return {};
+    }
+    const parsed = JSON.parse(body);
+    if (!isRecord(parsed)) {
+        throw new Error("request body must be a JSON object");
+    }
+    return parsed;
+}
+function sendText(response, status, text, contentType) {
+    response.statusCode = status;
+    response.setHeader("Content-Type", contentType);
+    response.setHeader("Cache-Control", "no-store");
+    response.end(text);
+}
+function sendJson(response, status, payload) {
+    sendText(response, status, JSON.stringify(payload), "application/json; charset=utf-8");
+}
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
 function isApprovalTerminalError(error) {
     return error instanceof StudioInstallApprovalError
         && (error.code === "pending_approval" || error.code === "access_pending" || error.code === "access_rejected");
@@ -3555,52 +4425,119 @@ function readSdkVersion() {
 function printHelp() {
     console.log(`Tapi CLI
 
-Usage:
-  tapi init --project PROJECT
+Usage:
+  tapi login
+  tapi init --project PROJECT
   tapi link --project PROJECT
   tapi studio install [--channel pilot] [--api-base-url URL]
   tapi studio
-  tapi studio open
-  tapi studio doctor
-  tapi services describe <servicemap.run>
+  tapi studio open
+  tapi studio doctor
+  tapi tapp create <tapp>
+  tapi queue create [display-name]
+  tapi tapp service add <tapp> <service.call> --service-map ID --entry ENTRY
+  tapi tapp queue add <tapp> <queue-id>
+  tapi runner setup --runner-id RUNNER --project TAPP
+  tapi runner slot set <runner-id> <slot-index> <queue-id>
+  tapi services describe <servicemap.run>
   tapi services sync
-  tapi services generate
   tapi triggers sync
   tapi sessions
   tapi service status
   tapi doctor
 
-Commands:
-  init            Create .tapi/project.json for this repo
+Commands:
+  login           Sign in with Firebase credentials for SDK commands
+  init            Create .tapi/project.json for this repo
   link            Rebind this repo to an existing Tapi project
   studio install  Download, verify, and run the Tapi Studio installer
-  studio          Open Tapi Studio for this repo
-  studio open     Open Tapi Studio for this repo
-  studio doctor   Check local SDK and Studio release configuration
-  services describe
+  studio          Open Tapi Studio for this repo
+  studio open     Open Tapi Studio for this repo
+  studio doctor   Check local SDK and Studio release configuration
+  tapp create     Create a Tapp
+  queue create    Create a queue for service-run routing
+  tapp service add
+                  Add a ServiceMap-backed service call to a Tapp
+  tapp queue add  Attach a queue to a Tapp
+  runner setup    Open the local runner queue/slot setup UI
+  runner slot set Assign a queue to a runner slot
+  services describe
                   Print a ServiceMap service-run input/output contract
   services sync   Save the service-run catalog to .tapi/services
-  services generate
-                  Write a TypeScript service-run wrapper from the catalog
   triggers sync   Upsert service triggers from tapi.config
   sessions        List dev-mode API sessions and open takeover sessions
   service         Inspect or control the local Tapi Windows service
   doctor          Alias for studio doctor
 `);
 }
+function printLoginHelp() {
+    console.log(`Tapi login
+
+Usage:
+  tapi login
+
+Signs in with the browser and caches Firebase credentials for SDK commands.
+`);
+}
+function printTappHelp() {
+    console.log(`Tapi Tapp commands
+
+Usage:
+  tapi tapp create <tapp> [--name NAME] [--api-base-url URL]
+  tapi tapp service add <tapp> <service.call> --service-map ID --entry ENTRY [--api-base-url URL]
+  tapi tapp queue add <tapp> <queue-id> [--api-base-url URL]
+
+Options:
+  --api-base-url <url>     Tapi API base URL
+  --server <url>           Alias for --api-base-url
+  --tapp-id <id>           Explicit Tapp id for tapp create
+  --name <name>            Display name for tapp create
+  --service-map <id>       Backing ServiceMap id
+  --entry <entry>          ServiceMap entry URL/name to launch
+  --expected-revision <r>  Optional ServiceMap revision guard
+`);
+}
+function printQueueHelp() {
+    console.log(`Tapi queue commands
+
+Usage:
+  tapi queue create [display-name] [--max-slots N] [--project TAPP] [--api-base-url URL]
+
+Options:
+  --api-base-url <url>  Tapi API base URL
+  --server <url>        Alias for --api-base-url
+  --project <id>        Optional project scope for the queue request
+  --max-slots <n>       Maximum runner slots this queue may use
+`);
+}
+function printRunnerHelp() {
+    console.log(`Tapi runner commands
+
+Usage:
+  tapi runner setup --runner-id RUNNER --project TAPP [--port PORT] [--no-open] [--api-base-url URL]
+  tapi runner slot set <runner-id> <slot-index> <queue-id> [--project TAPP] [--api-base-url URL]
+
+Options:
+  --api-base-url <url>  Tapi API base URL
+  --server <url>        Alias for --api-base-url
+  --project <id>        Tapi project id; defaults to TAPI_PROJECT_ID or .tapi/project.json
+  --runner-id <id>      Runner id for setup; defaults to TAPI_RUNNER_ID
+  --port <n>            Local setup UI port; defaults to 17687
+  --no-open             Print the setup URL without opening a browser
+`);
+}
 function printSessionsHelp() {
     console.log(`Tapi dev session commands
 
-Usage:
-  tapi sessions [--api-base-url URL] [--api-key KEY] [--project PROJECT]
-  tapi sessions list [--json] [--site SITE]
-  tapi sessions open <session-id> [--api-base-url URL] [--api-key KEY] [--project PROJECT]
-
-Options:
-  --api-base-url <url>   Tapi API base URL
-  --server <url>         Alias for --api-base-url
-  --api-key <key>        Tapi API key; defaults to TAPI_API_KEY
-  --project <id>         Tapi project id; defaults to TAPI_PROJECT_ID or .tapi/project.json
+Usage:
+  tapi sessions [--api-base-url URL] [--project PROJECT]
+  tapi sessions list [--json] [--site SITE]
+  tapi sessions open <session-id> [--api-base-url URL] [--project PROJECT]
+
+Options:
+  --api-base-url <url>   Tapi API base URL
+  --server <url>         Alias for --api-base-url
+  --project <id>         Tapi project id; defaults to TAPI_PROJECT_ID or .tapi/project.json
   --site <name>          Limit sessions to one sitemap/site
   --json                 Print raw grouped session JSON
   --no-interactive       Print the grouped list without the arrow-key picker
@@ -3609,32 +4546,28 @@ Options:
 function printServicesHelp() {
     console.log(`Tapi ServiceMap service-run commands
 
-Usage:
-  tapi services describe <servicemap.run> [--api-base-url URL] [--api-key KEY] [--project PROJECT]
-  tapi services sync [--api-base-url URL] [--api-key KEY] [--project PROJECT]
-  tapi services generate [--api-base-url URL] [--api-key KEY] [--project PROJECT] [--out FILE]
-
-Options:
-  --api-base-url <url>   Tapi API base URL
-  --server <url>         Alias for --api-base-url
-  --api-key <key>        Tapi API key; defaults to TAPI_API_KEY
-  --project <id>         Tapi project id; defaults to TAPI_PROJECT_ID or .tapi/project.json
+Usage:
+  tapi services describe <servicemap.run> [--api-base-url URL] [--project PROJECT]
+  tapi services sync [--api-base-url URL] [--project PROJECT]
+
+Options:
+  --api-base-url <url>   Tapi API base URL
+  --server <url>         Alias for --api-base-url
+  --project <id>         Tapi project id; defaults to TAPI_PROJECT_ID or .tapi/project.json
   --catalog <path>       Catalog JSON output path
-  --out <path>           TypeScript wrapper output path
 `);
 }
 function printTriggersHelp() {
     console.log(`Tapi service trigger commands
 
-Usage:
-  tapi triggers sync [--config FILE] [--api-base-url URL] [--api-key KEY] [--project PROJECT]
-
-Options:
-  --config <path>        Trigger config path; defaults to tapi.config.ts/js/json in the workspace root
-  --api-base-url <url>   Tapi API base URL
-  --server <url>         Alias for --api-base-url
-  --api-key <key>        Tapi API key; defaults to TAPI_API_KEY
-  --project <id>         Tapi project id; defaults to TAPI_PROJECT_ID or .tapi/project.json
+Usage:
+  tapi triggers sync [--config FILE] [--api-base-url URL] [--project PROJECT]
+
+Options:
+  --config <path>        Trigger config path; defaults to tapi.config.ts/js/json in the workspace root
+  --api-base-url <url>   Tapi API base URL
+  --server <url>         Alias for --api-base-url
+  --project <id>         Tapi project id; defaults to TAPI_PROJECT_ID or .tapi/project.json
 
 Config:
   export default {
@@ -3643,7 +4576,7 @@ Config:
         serviceRun: "schwab.get_balance",
         interval: "1h",
         inputs: { accountId: "main" },
-        runtime: { profileRef: "perm_default" },
+        runtime: { owner: "service_run", profileRef: "perm_default" },
       },
     },
   };
@@ -3756,7 +4689,15 @@ function serializeError(error) {
 }
 function isCliEntrypoint() {
     const invokedPath = process.argv[1];
-    return Boolean(invokedPath && resolve(invokedPath) === fileURLToPath(import.meta.url));
+    return Boolean(invokedPath && realCliPath(invokedPath) === realCliPath(fileURLToPath(import.meta.url)));
+}
+function realCliPath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
 }
 if (isCliEntrypoint()) {
     runCli().then((code) => {