tinker-agent 2.12.0 → 3.0.0

package/src/agent/runtime-session-contracts.ts

@@ -1,3 +1,4 @@
+import type { SessionLease } from "../session/session-lock";
 import type {
   ProviderRetryDecision,
   ProviderRetrySnapshot,
@@ -100,6 +101,12 @@ export type RuntimeSession = {
     signal: AbortSignal,
     prospectiveMessageImageCount: number,
   ): Promise<ImportedImageAsset>;
+  importImageBytes(
+    bytes: Buffer,
+    originalName: string,
+    signal: AbortSignal,
+    prospectiveMessageImageCount: number,
+  ): Promise<ImportedImageAsset>;
   verifyImageAssets(
     assets: readonly ImageAssetRef[],
     signal: AbortSignal,
@@ -127,6 +134,7 @@ export type RuntimeSession = {
   askUser(): AskUserSnapshot;
   subscribeAskUser(listener: () => void): () => void;
   resolveAskUser(response: AskUserResolution): Promise<void>;
+  retainSessionLease(): SessionLease;
   dispose(reason: SessionDisposeReason): Promise<void>;
 };
 
@@ -208,6 +216,7 @@ export type SkillsUpdateSummary = {
 };
 
 export type CommonRuntimeSessionInput = {
+  sessionLease?: SessionLease;
   workspaceRoot: string;
   homeRoot?: string;
   modelName: string;

package/src/agent/runtime-session.ts

@@ -170,6 +170,7 @@ const defaultDependencies: RuntimeSessionFactoryDependencies = {
           ...(input.homeRoot === undefined ? {} : { homeRoot: input.homeRoot }),
         })
       : SessionStore.openExisting({
+          lease: input.sessionLease,
           workspaceRoot: input.workspaceRoot,
           sessionId: input.selection.sessionId,
           ...(input.homeRoot === undefined ? {} : { homeRoot: input.homeRoot }),
@@ -774,6 +775,29 @@ class DefaultRuntimeSession implements RuntimeSession {
     signal: AbortSignal,
     prospectiveMessageImageCount: number,
   ): Promise<ImportedImageAsset> {
+    const assertImageAllowed = this.imageAdmissionCheck(prospectiveMessageImageCount);
+    if (this.supportsImageInput()) assertImageAllowed();
+    return this.assetStore.importWorkspaceFile(sourcePath, {
+      signal,
+      accept: assertImageAllowed,
+    });
+  }
+
+  async importImageBytes(
+    bytes: Buffer,
+    originalName: string,
+    signal: AbortSignal,
+    prospectiveMessageImageCount: number,
+  ): Promise<ImportedImageAsset> {
+    const assertImageAllowed = this.imageAdmissionCheck(prospectiveMessageImageCount);
+    if (this.supportsImageInput()) assertImageAllowed();
+    return this.assetStore.importBytes(bytes, originalName, {
+      signal,
+      accept: assertImageAllowed,
+    });
+  }
+
+  private imageAdmissionCheck(prospectiveMessageImageCount: number): () => void {
     if (this.state !== "ready") {
       throw new Error(`Cannot import an image while RuntimeSession is ${this.state}.`);
     }
@@ -806,13 +830,7 @@ class DefaultRuntimeSession implements RuntimeSession {
       }
     };
 
-    if (this.supportsImageInput()) {
-      assertImageAllowed();
-    }
-    return this.assetStore.importWorkspaceFile(sourcePath, {
-      signal,
-      accept: assertImageAllowed,
-    });
+    return assertImageAllowed;
   }
 
   async verifyImageAssets(
@@ -1056,6 +1074,10 @@ class DefaultRuntimeSession implements RuntimeSession {
     return completion;
   }
 
+  retainSessionLease() {
+    return this.store.retainLease();
+  }
+
   dispose(reason: SessionDisposeReason): Promise<void> {
     this.disposePromise ??= this.performDispose(reason);
     return this.disposePromise;

package/src/cli/command-line.ts

@@ -4,10 +4,27 @@ import type { PromptSource } from "./prompt-source";
 import { CliUsageError, type CliCommandScope } from "./output";
 
 export type CliCommand =
-  | { readonly type: "tui"; readonly profileName?: string }
+  | { readonly type: "tui"; readonly profileName?: string; readonly local?: boolean }
   | { readonly type: "update" }
-  | { readonly type: "serve"; readonly configPath: string }
-  | { readonly type: "connect"; readonly configPath: string }
+  | {
+      readonly type: "serve";
+      readonly configPath?: string;
+      readonly background?: boolean;
+      readonly install?: boolean;
+      readonly uninstall?: boolean;
+      readonly stop?: boolean;
+      readonly restart?: boolean;
+      readonly force?: boolean;
+      readonly status?: boolean;
+    }
+  | {
+      readonly type: "connect";
+      readonly configPath: string;
+      readonly tui?: boolean;
+      readonly workspaceId?: string;
+      readonly sessionId?: string;
+      readonly serviceConfigPath?: string;
+    }
   | {
       readonly type: "run";
       readonly profileName?: string;
@@ -45,6 +62,7 @@ export async function parseCommandLine(
     .helpOption(contract.helpFlags)
     .version(packageVersion, contract.versionFlags)
     .option(contract.tui.profileOption.flags, contract.tui.profileOption.description)
+    .option(contract.tui.localOption.flags, contract.tui.localOption.description)
     .helpCommand(contract.helpCommand.command, contract.helpCommand.description)
     .showHelpAfterError('Run "tinker --help" for usage.')
     .showSuggestionAfterError(false)
@@ -61,9 +79,10 @@ export async function parseCommandLine(
     });
 
   program.action(() => {
-    const { profile } = program.opts<{ profile?: string }>();
+    const { profile, local } = program.opts<{ profile?: string; local?: boolean }>();
     selectedCommand = Object.freeze({
       type: "tui",
+      ...(local ? { local: true } : {}),
       ...(profile === undefined
         ? {}
         : { profileName: validateProfile(profile, "root") }),
@@ -134,17 +153,140 @@ export async function parseCommandLine(
 
   for (const type of ["serve", "connect"] as const) {
     const command = contract[type];
-    program
+    const subcommand = program
       .command(command.command)
       .description(command.description)
-      .requiredOption(command.configOption.flags, command.configOption.description)
       .allowExcessArguments(false)
-      .exitOverride()
-      .action((options: { config: string }) => {
-        if (!options.config.trim())
+      .exitOverride();
+    if (type === "serve") {
+      subcommand.option(command.configOption.flags, command.configOption.description);
+      subcommand.option(
+        contract.serve.backgroundOption.flags,
+        contract.serve.backgroundOption.description,
+      );
+      subcommand.option(
+        contract.serve.statusOption.flags,
+        contract.serve.statusOption.description,
+      );
+      for (const option of contract.serve.residentOptions)
+        subcommand.option(option.flags, option.description);
+    } else
+      subcommand.requiredOption(
+        command.configOption.flags,
+        command.configOption.description,
+      );
+    if (type === "connect") {
+      for (const option of [
+        contract.connect.tuiOption,
+        contract.connect.workspaceOption,
+        contract.connect.sessionOption,
+        contract.connect.serviceConfigOption,
+      ])
+        subcommand.option(option.flags, option.description);
+    }
+    subcommand.action(
+      (options: {
+        config?: string;
+        background?: boolean;
+        install?: boolean;
+        uninstall?: boolean;
+        stop?: boolean;
+        restart?: boolean;
+        force?: boolean;
+        status?: boolean;
+        tui?: boolean;
+        workspace?: string;
+        session?: string;
+        serviceConfig?: string;
+      }) => {
+        if (options.config !== undefined && !options.config.trim())
           throw new CliUsageError("--config requires a non-empty path.", type);
-        selectedCommand = Object.freeze({ type, configPath: options.config });
-      });
+        if (type === "serve") {
+          if (
+            [
+              options.background,
+              options.status,
+              options.install,
+              options.uninstall,
+              options.stop,
+              options.restart,
+            ].filter(Boolean).length > 1
+          )
+            throw new CliUsageError(
+              "Service management modes are mutually exclusive.",
+              type,
+            );
+          if (
+            options.force &&
+            ![options.install, options.uninstall, options.stop, options.restart].some(
+              Boolean,
+            )
+          )
+            throw new CliUsageError(
+              "--force requires --install, --uninstall, --stop or --restart.",
+              type,
+            );
+          selectedCommand = Object.freeze({
+            ...(options.install ? { install: true } : {}),
+            ...(options.uninstall ? { uninstall: true } : {}),
+            ...(options.stop ? { stop: true } : {}),
+            ...(options.restart ? { restart: true } : {}),
+            ...(options.force ? { force: true } : {}),
+            type,
+            ...(options.config === undefined ? {} : { configPath: options.config }),
+            ...(options.background ? { background: true } : {}),
+            ...(options.status ? { status: true } : {}),
+          });
+          return;
+        }
+        if (options.config === undefined)
+          throw new CliUsageError("--config is required.", type);
+        if (
+          options.tui ||
+          options.workspace !== undefined ||
+          options.session !== undefined ||
+          options.serviceConfig !== undefined
+        ) {
+          if (
+            !options.tui ||
+            (options.workspace !== undefined && !options.workspace.trim())
+          )
+            throw new CliUsageError(
+              "--workspace, --session and --service-config require --tui; workspace ID must be non-empty.",
+              type,
+            );
+          if (options.serviceConfig !== undefined && !options.serviceConfig.trim())
+            throw new CliUsageError(
+              "--service-config requires a non-empty path.",
+              type,
+            );
+          if (
+            options.workspace !== undefined &&
+            !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,100}$/.test(options.workspace)
+          )
+            throw new CliUsageError("Invalid workspace ID.", type);
+          if (
+            options.session !== undefined &&
+            !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(
+              options.session,
+            )
+          )
+            throw new CliUsageError("Invalid session ID.", type);
+          selectedCommand = Object.freeze({
+            type,
+            configPath: options.config,
+            tui: true,
+            ...(options.workspace === undefined
+              ? {}
+              : { workspaceId: options.workspace }),
+            ...(options.session ? { sessionId: options.session } : {}),
+            ...(options.serviceConfig === undefined
+              ? {}
+              : { serviceConfigPath: options.serviceConfig }),
+          });
+        } else selectedCommand = Object.freeze({ type, configPath: options.config });
+      },
+    );
   }
 
   program
@@ -176,6 +318,11 @@ export async function parseCommandLine(
   if (selectedCommand === undefined) {
     throw new Error("Commander completed without selecting a command.");
   }
+  if (selectedCommand.type !== "tui" && program.opts<{ local?: boolean }>().local)
+    throw new CliUsageError(
+      "--local only applies to the default TUI.",
+      selectedCommand.type,
+    );
   const topLevelProfile = program.opts<{ profile?: string }>().profile;
   if (selectedCommand.type === "run" && topLevelProfile !== undefined) {
     throw new CliUsageError(
@@ -232,6 +379,7 @@ function preflightArgv(args: readonly string[]): CliCommandScope {
         index += profile.consumedNext ? 1 : 0;
         continue;
       }
+      if (token === "--local") continue;
       if (token.startsWith("-")) {
         rootBlocked = true;
         continue;

package/src/cli/connect-runner.tsx

@@ -1,15 +1,27 @@
+import { App } from "../tui/app";
+import { prepareShikiHighlighter } from "../tui/shiki-highlighter";
+import { clipboardWriterForEnvironment } from "../tui/clipboard";
+import { createRemoteTuiClient } from "../client/remote-workspace-client";
 import { render } from "ink";
 import { RemoteClient, loadRemoteClientConfig } from "../remote/client";
 import { RemoteApp } from "../tui/remote-app";
 import type { CliOutputWriter } from "./output";
+import { resolveConnectedWorkspace } from "./connect-workspace";
 
 export async function runConnect(input: {
   configPath: string;
   env: NodeJS.ProcessEnv;
   stdout: CliOutputWriter;
+  cwd?: string;
+  tui?: boolean;
+  workspaceId?: string;
+  sessionId?: string;
+  profileName?: string;
+  serviceConfigPath?: string;
 }): Promise<number> {
   if (!process.stdin.isTTY)
     throw new Error("tinker connect requires an interactive terminal.");
+  if (input.tui) return runFullTui(input);
   const client = new RemoteClient(await loadRemoteClientConfig(input.configPath));
   let instance: ReturnType<typeof render> | undefined;
   try {
@@ -24,3 +36,54 @@ export async function runConnect(input: {
     process.stdin.pause();
   }
 }
+
+async function runFullTui(input: {
+  configPath: string;
+  env: NodeJS.ProcessEnv;
+  cwd?: string;
+  workspaceId?: string;
+  sessionId?: string;
+  profileName?: string;
+  serviceConfigPath?: string;
+}): Promise<number> {
+  const config = await loadRemoteClientConfig(input.configPath);
+  const workspaceId = await resolveConnectedWorkspace({
+    ...input,
+    config,
+    cwd: input.cwd ?? process.cwd(),
+  });
+  const connection = await createRemoteTuiClient(
+    config,
+    workspaceId,
+    input.sessionId,
+    input.profileName,
+  );
+  let instance: ReturnType<typeof render> | undefined;
+  try {
+    const [history, projectSlashCommands] = await Promise.all([
+      connection.client.loadHistory(),
+      connection.client.projectCommands(),
+      prepareShikiHighlighter(),
+    ]);
+    instance = render(
+      <App
+        sessionController={connection.client}
+        history={history}
+        projectSlashCommands={projectSlashCommands}
+        readGitBranch={connection.client.readGitBranch}
+        fileLister={connection.client.listFiles}
+        readViewFile={connection.client.readFile}
+        writeClipboard={clipboardWriterForEnvironment(input.env)}
+        listStoredMemories={connection.client.listStoredMemories}
+      />,
+      { incrementalRendering: true },
+    );
+    await instance.waitUntilExit();
+    return 0;
+  } finally {
+    instance?.unmount();
+    await connection.close({ type: "client_exit" });
+    if (process.stdin.isTTY) process.stdin.setRawMode(false);
+    process.stdin.pause();
+  }
+}

package/src/cli/connect-workspace.ts

@@ -0,0 +1,33 @@
+import { RemoteClient, type RemoteClientConfig } from "../remote/client";
+import {
+  loadLocalServiceTarget,
+  registerLocalWorkspace,
+} from "../remote/local-service-discovery";
+import { ensureLocalService } from "./local-service-start";
+
+export async function resolveConnectedWorkspace(input: {
+  config: RemoteClientConfig;
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  workspaceId?: string;
+  serviceConfigPath?: string;
+}): Promise<string> {
+  const probe = new RemoteClient(input.config, false);
+  try {
+    if (input.serviceConfigPath) {
+      const target = await loadLocalServiceTarget(input.serviceConfigPath, input.env);
+      const local = await ensureLocalService(target, input.env);
+      const remote = await probe.request<{ instanceId: string }>("/v1/service");
+      if (remote.instanceId !== local.instanceId)
+        throw new Error(
+          "Client pairing points to a different service. Use the client configuration for this local service before registering a workspace.",
+        );
+      if (!input.workspaceId)
+        return (await registerLocalWorkspace(target, input.cwd)).id;
+    }
+    if (input.workspaceId) return input.workspaceId;
+    return (await probe.resolveWorkspace(input.cwd)).id;
+  } finally {
+    await probe.close();
+  }
+}

package/src/cli/default-service-config.ts

@@ -0,0 +1,163 @@
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  defaultServiceConfigPath,
+  loadLocalServiceTarget,
+} from "../remote/local-service-discovery";
+import { loadRemoteClientConfig } from "../remote/client";
+import { authenticateDevice } from "../remote/config";
+import { ensureLocalService } from "./local-service-start";
+
+/** Publish an entire credential/config bundle atomically; competing first launches reuse the winner. */
+export async function prepareDefaultServiceConfig(
+  env: NodeJS.ProcessEnv,
+): Promise<string> {
+  if (process.platform === "win32")
+    throw new Error(
+      "Default service startup requires macOS/Linux. Use tinker --local on Windows.",
+    );
+  const configPath = defaultServiceConfigPath(env);
+  const directory = path.dirname(configPath);
+  if (await exists(directory)) {
+    if (!(await exists(configPath)))
+      throw new Error(
+        `Service directory has no service.json: ${directory}. Complete its configuration or use tinker --local.`,
+      );
+    return configPath;
+  }
+  await mkdir(path.dirname(directory), { recursive: true, mode: 0o700 });
+  const temporary = `${directory}.setup-${randomUUID()}`;
+  await mkdir(temporary, { mode: 0o700 });
+  try {
+    const child = Bun.spawn(
+      [
+        "openssl",
+        "req",
+        "-x509",
+        "-newkey",
+        "rsa:2048",
+        "-nodes",
+        "-sha256",
+        "-days",
+        "365",
+        "-subj",
+        "/CN=Tinker local service",
+        "-addext",
+        "subjectAltName=DNS:localhost,IP:127.0.0.1",
+        "-addext",
+        "basicConstraints=critical,CA:TRUE",
+        "-keyout",
+        path.join(temporary, "server.key"),
+        "-out",
+        path.join(temporary, "server.crt"),
+      ],
+      { stdout: "ignore", stderr: "pipe" },
+    );
+    const [error, code] = await Promise.all([
+      new Response(child.stderr).text(),
+      child.exited,
+    ]);
+    if (code !== 0)
+      throw new Error(`Cannot prepare local TLS certificate: ${error.trim()}`);
+    await chmod(path.join(temporary, "server.key"), 0o600);
+    await chmod(path.join(temporary, "server.crt"), 0o600);
+    const token = randomBytes(32).toString("base64url");
+    await writeFile(
+      path.join(temporary, "service.json"),
+      JSON.stringify(
+        {
+          version: 1,
+          localBootstrap: 1,
+          hostname: "127.0.0.1",
+          port: 0,
+          tls: { certFile: "./server.crt", keyFile: "./server.key" },
+          devices: [
+            {
+              id: "local-terminal",
+              name: "Local terminal",
+              tokenSha256: createHash("sha256").update(token).digest("hex"),
+            },
+          ],
+          workspaces: [],
+        },
+        null,
+        2,
+      ) + "\n",
+      { mode: 0o600 },
+    );
+    await writeFile(
+      path.join(temporary, "client.json"),
+      JSON.stringify(
+        {
+          url: "https://127.0.0.1:1",
+          token,
+          caFile: "./server.crt",
+        },
+        null,
+        2,
+      ) + "\n",
+      { mode: 0o600 },
+    );
+    try {
+      await rename(temporary, directory);
+    } catch (error) {
+      if (
+        !["EEXIST", "ENOTEMPTY"].includes((error as NodeJS.ErrnoException).code ?? "")
+      )
+        throw error;
+      if (!(await exists(configPath)))
+        throw new Error(`Incomplete service configuration at ${directory}.`, {
+          cause: error,
+        });
+    }
+    return configPath;
+  } finally {
+    await rm(temporary, { recursive: true, force: true });
+  }
+}
+
+export async function prepareDefaultConnection(env: NodeJS.ProcessEnv) {
+  const serviceConfigPath = await prepareDefaultServiceConfig(env);
+  const configPath = path.join(path.dirname(serviceConfigPath), "client.json");
+  // Validate credentials before starting a service; never replace an existing pairing.
+  const client = await loadRemoteClientConfig(configPath);
+  const target = await loadLocalServiceTarget(serviceConfigPath, env);
+  if (!authenticateDevice(`Bearer ${client.token}`, target.config.devices))
+    throw new Error(
+      `Local client credentials do not match ${serviceConfigPath}. Repair client.json before connecting.`,
+    );
+  const instance = await ensureLocalService(target, env);
+  const raw = JSON.parse(await readFile(serviceConfigPath, "utf8")) as {
+    localBootstrap?: unknown;
+  };
+  if (raw.localBootstrap === 1) {
+    // Auto-created local pairing follows the actual loopback port after every restart.
+    const pairing = JSON.parse(await readFile(configPath, "utf8")) as Record<
+      string,
+      unknown
+    >;
+    const temporary = `${configPath}.${randomUUID()}.tmp`;
+    try {
+      await writeFile(
+        temporary,
+        JSON.stringify({ ...pairing, url: instance.url }, null, 2) + "\n",
+        { mode: 0o600 },
+      );
+      await rename(temporary, configPath);
+    } finally {
+      await rm(temporary, { force: true });
+    }
+  }
+  return { serviceConfigPath, configPath };
+}
+
+async function exists(filename: string): Promise<boolean> {
+  try {
+    await stat(filename);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}

package/src/cli/default-tui-runner.ts

@@ -0,0 +1,23 @@
+import { resolveUserPath } from "./public-config-contract";
+import type { CliOutputWriter } from "./output";
+import { prepareDefaultConnection } from "./default-service-config";
+import { runConnect } from "./connect-runner";
+
+export async function runDefaultTui(input: {
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  stdout: CliOutputWriter;
+  profileName?: string;
+}): Promise<number> {
+  if (!process.stdin.isTTY)
+    throw new Error(
+      "tinker requires an interactive terminal. Use tinker run for one-shot execution.",
+    );
+  const configs = await prepareDefaultConnection(input.env);
+  return runConnect({
+    ...input,
+    ...configs,
+    cwd: resolveUserPath(input.cwd, input.env.TINKER_WORKSPACE?.trim() || "."),
+    tui: true,
+  });
+}