tinker-agent 2.13.0 → 3.0.0

package/src/cli/interactive-runtime.ts

@@ -0,0 +1,87 @@
+import {
+  createRuntimeSession,
+  type CreateRuntimeSessionInput,
+} from "../agent/runtime-session";
+import type { AssistantTextDeltaSink } from "../agent/assistant-text-delta";
+import type { EventSink } from "../events/event-sink";
+import {
+  buildSystemPrompt,
+  loadProjectInstructions,
+  projectInstructionManifest,
+} from "../instructions/project-instructions";
+import { createReasoningEffortController } from "../model/reasoning-effort";
+import { loadSkillCatalog } from "../skills/skill-loader";
+import type { RunnerConfig } from "./config";
+import type { PublicToolingConfig } from "./public-config-contract";
+import {
+  createRunnerModelClient,
+  createWebFetchRefiner,
+  RUNTIME_INSTRUCTIONS,
+} from "./runner-dependencies";
+
+type InteractiveRuntimeInput = {
+  sessionLease?: CreateRuntimeSessionInput["sessionLease"];
+  config: RunnerConfig;
+  workspaceRoot: string;
+  homeRoot?: string;
+  selection: CreateRuntimeSessionInput["selection"];
+  toolingConfig: PublicToolingConfig;
+  env: NodeJS.ProcessEnv;
+  sink: EventSink & AssistantTextDeltaSink;
+  owner: "local-tui" | "service";
+};
+
+// Both interactive owners expose the same runtime interaction and undo capabilities.
+const CAPABILITIES = {
+  "local-tui": { enableTurnUndo: true, enableProviderRetryPrompt: true },
+  service: { enableTurnUndo: true, enableProviderRetryPrompt: true },
+} as const;
+
+/** Composition only: callers retain config selection and runtime ownership. */
+export async function buildInteractiveRuntimeInput(
+  input: InteractiveRuntimeInput,
+): Promise<CreateRuntimeSessionInput> {
+  const { config, workspaceRoot, env, sink } = input;
+  const reasoning = createReasoningEffortController(config.reasoning);
+  const modelClient = createRunnerModelClient(config, undefined, env, reasoning);
+  const projectInstructions = await loadProjectInstructions(workspaceRoot);
+  const skillCatalog = await loadSkillCatalog({ workspaceRoot });
+  return {
+    sessionLease: input.sessionLease,
+    workspaceRoot,
+    ...(input.homeRoot === undefined ? {} : { homeRoot: input.homeRoot }),
+    ...(input.selection.mode === "new"
+      ? { selection: input.selection }
+      : { selection: input.selection }),
+    modelName: config.modelName,
+    profileName: config.profileName,
+    maxIterations: config.maxIterations,
+    includeReasoningContent: config.includeReasoningContent,
+    contextProfile: config.contextProfile,
+    contextBudget: config.contextBudget,
+    modelClient,
+    systemPrompt: buildSystemPrompt({
+      workspaceRoot,
+      runtimeInstructions: RUNTIME_INSTRUCTIONS(workspaceRoot),
+      projectInstructions,
+    }),
+    projectInstruction: projectInstructionManifest(projectInstructions),
+    skillCatalog,
+    presentationSinks: [sink],
+    assistantTextDeltaSink: sink,
+    toolingConfig: input.toolingConfig,
+    webFetchRefiner: createWebFetchRefiner(config, env, reasoning),
+    ...CAPABILITIES[input.owner],
+    enableAskUser: true,
+    // "tui" currently denotes an interactive guard, including hosted sessions.
+    bashGuard: {
+      mode: config.bashGuardMode,
+      source: config.bashGuardSource,
+      surface: "tui",
+    },
+  };
+}
+
+export async function createInteractiveRuntimeSession(input: InteractiveRuntimeInput) {
+  return createRuntimeSession(await buildInteractiveRuntimeInput(input));
+}

package/src/cli/local-service-start.ts

@@ -0,0 +1,131 @@
+import { startSupervisor } from "./service-supervisor";
+import { loadPackageMetadata } from "./package-metadata";
+import { spawn, type ChildProcess } from "node:child_process";
+import { constants } from "node:fs";
+import { chmod, mkdir, open } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseSessionId } from "../ids/runtime-id";
+import { inspectSessionLock, SessionLease } from "../session/session-lock";
+import { SessionError } from "../session/session-errors";
+import { SERVICE_LEASE_ID } from "../remote/service-store";
+import {
+  discoverLocalService,
+  localServicePaths,
+  type LocalServiceInstance,
+  type LocalServiceTarget,
+} from "../remote/local-service-discovery";
+
+const STARTUP_LEASE_ID = parseSessionId("00000000-0000-7000-8000-000000000002");
+
+/** Shared by the explicit background command and the default client entry. */
+export async function ensureLocalService(
+  target: LocalServiceTarget,
+  env: NodeJS.ProcessEnv,
+  timeoutMs = 30000,
+): Promise<LocalServiceInstance> {
+  const version = (await loadPackageMetadata()).version;
+  const checkVersion = (instance: LocalServiceInstance) => {
+    if (instance.appVersion && instance.appVersion !== version)
+      throw new Error(
+        "A different Tinker version is running. Use tinker serve --restart before connecting; active work is not interrupted automatically.",
+      );
+    return instance;
+  };
+  const paths = localServicePaths(target.config.stateDirectory);
+  if (process.platform === "win32")
+    throw new Error("Background service startup currently requires macOS/Linux.");
+  const deadline = Date.now() + timeoutMs;
+  const existing = await discoverLocalService(target);
+  if (existing) return checkVersion(existing);
+  await mkdir(paths.startup, { recursive: true, mode: 0o700 });
+  await chmod(target.config.stateDirectory, 0o700);
+  await chmod(paths.startup, 0o700);
+  let lease: SessionLease | undefined;
+  while (Date.now() < deadline && !lease) {
+    const running = await discoverLocalService(target);
+    if (running) return checkVersion(running);
+    try {
+      lease = await SessionLease.acquire({
+        sessionDirectory: paths.startup,
+        sessionId: STARTUP_LEASE_ID,
+      });
+    } catch (error) {
+      // A competing process may still be writing its freshly-created lease.
+      if (
+        !(error instanceof SessionError) ||
+        !["SESSION_LOCKED", "SESSION_LOCK_CORRUPT"].includes(error.code)
+      )
+        throw error;
+      await Bun.sleep(50);
+    }
+  }
+  if (!lease)
+    throw new Error(
+      `Timed out waiting for service startup ownership. Check ${paths.startup}.`,
+    );
+  let supervised = false;
+  let child: ChildProcess | undefined;
+  let childFailure: Error | undefined;
+  try {
+    while (Date.now() < deadline) {
+      const running = await discoverLocalService(target);
+      if (running) return checkVersion(running);
+      if (childFailure) throw childFailure;
+      if (child && (child.exitCode !== null || child.signalCode !== null))
+        throw new Error(`Service exited before becoming ready. Check ${paths.log}.`);
+      if (!child && !supervised) {
+        const ownership = await inspectSessionLock({
+          sessionDirectory: target.config.stateDirectory,
+          sessionId: SERVICE_LEASE_ID,
+        });
+        // A foreground service or an orphaned starter's child may be initializing.
+        // Never kill it, steal its lease, or start a second runtime owner.
+        if (ownership === "none" || ownership === "stale") {
+          supervised = await startSupervisor(target);
+          if (supervised) continue;
+          const log = await open(
+            paths.log,
+            constants.O_WRONLY |
+              constants.O_CREAT |
+              constants.O_APPEND |
+              constants.O_NOFOLLOW,
+            0o600,
+          );
+          try {
+            await log.chmod(0o600);
+            child = spawn(
+              process.execPath,
+              [
+                fileURLToPath(new URL("./index.ts", import.meta.url)),
+                "serve",
+                "--config",
+                target.configPath,
+              ],
+              {
+                cwd: path.dirname(target.configPath),
+                env: { ...env, TINKER_HOME: target.homeRoot },
+                detached: true,
+                stdio: ["ignore", log.fd, log.fd],
+              },
+            );
+            child.once("error", () => {
+              childFailure = new Error(
+                `Could not launch the service. Check ${paths.log}.`,
+              );
+            });
+            child.unref();
+          } finally {
+            await log.close();
+          }
+        }
+      }
+      await Bun.sleep(50);
+    }
+    throw new Error(
+      `Service is not ready. A live owner is left running; check ${paths.log} and ${paths.instance}.`,
+    );
+  } finally {
+    await lease.release();
+  }
+}

package/src/cli/local-tui-client.ts

@@ -0,0 +1,234 @@
+import type { RuntimeSession } from "../agent/runtime-session";
+import type { EventSink } from "../events/event-sink";
+import type { AgentEvent } from "../events/types";
+import type {
+  AssistantTextDeltaSink,
+  AssistantTextDeltaUpdate,
+} from "../agent/assistant-text-delta";
+import { createUuidV7 } from "../ids/uuid-v7";
+import type { SessionId } from "../ids/runtime-id";
+import { ResumeProjectionReader } from "../session/resume-projection";
+import { SessionCatalog } from "../session/session-catalog";
+import type { TuiSessionView } from "../tui/tui-session-controller";
+import { TuiProjectionStore } from "../tui/tui-projection-store";
+import {
+  LocalWorkspaceClient,
+  createLocalSessionBinding,
+  type OwnedSessionBinding,
+} from "../client/local-workspace-client";
+import type { SessionClient, ClientConnection } from "../client/session-client";
+import {
+  deriveRunnerConfig,
+  type ResolvedPublicConfig,
+  type RunnerConfig,
+} from "./config";
+import { createInteractiveRuntimeSession } from "./interactive-runtime";
+import { resolveSessionProfileName } from "./model-profiles";
+import type { ClientModelProfile } from "../client/model-catalog";
+
+export async function createLocalTuiClient(options: {
+  publicConfig: ResolvedPublicConfig;
+  initialRunnerConfig: RunnerConfig;
+  env: NodeJS.ProcessEnv;
+  workspaceRoot: string;
+}): Promise<ClientConnection<TuiSessionView>> {
+  const { workspaceRoot } = options;
+  const config = options.initialRunnerConfig;
+  const profiles =
+    options.publicConfig.mode === "profile" ? options.publicConfig.profiles : undefined;
+  const createSessionForConfig = async (
+    sessionConfig: RunnerConfig,
+    mode: "new" | "resume",
+    sessionId: SessionId,
+    sink: EventSink & AssistantTextDeltaSink,
+  ): Promise<RuntimeSession> =>
+    createInteractiveRuntimeSession({
+      config: sessionConfig,
+      workspaceRoot,
+      selection: { mode, sessionId },
+      toolingConfig: options.publicConfig.tooling,
+      env: options.env,
+      sink,
+      owner: "local-tui",
+    });
+
+  const projectionStore = new TuiProjectionStore({
+    sessionId: config.sessionId,
+    modelName: config.modelName,
+    workspaceRoot,
+  });
+  const initialSession = await createSessionForConfig(
+    config,
+    "new",
+    config.sessionId,
+    projectionStore,
+  );
+  try {
+    const catalog = new SessionCatalog({ workspaceRoot });
+
+    const openStoredSession = async (
+      sessionId: SessionId,
+    ): Promise<OwnedSessionBinding<TuiProjectionStore>> => {
+      const deferred = new DeferredProjectionSink();
+      const summary = await catalog.get(sessionId);
+      const resumeConfig = deriveRunnerConfig(options.publicConfig, {
+        sessionId,
+        ...(profiles === undefined
+          ? {}
+          : { profileName: resolveSessionProfileName(profiles, summary) }),
+      });
+      const runtimeSession = await createSessionForConfig(
+        resumeConfig,
+        "resume",
+        sessionId,
+        deferred,
+      );
+      const targetProjection = new TuiProjectionStore({
+        sessionId,
+        modelName: resumeConfig.modelName,
+        workspaceRoot,
+      });
+      try {
+        targetProjection.hydrate(
+          await ResumeProjectionReader.read({
+            workspaceRoot,
+            sessionId,
+            modelName: resumeConfig.modelName,
+          }),
+        );
+        await deferred.attach(targetProjection);
+      } catch (error) {
+        await runtimeSession
+          .dispose({ type: "runner_failed", error: errorMessage(error) })
+          .catch(() => undefined);
+        throw error;
+      }
+      return createLocalSessionBinding({
+        runtimeSession,
+        modelName: resumeConfig.modelName,
+        workspaceRoot,
+        profileName: resumeConfig.profileName,
+        projectionStore: targetProjection,
+      });
+    };
+
+    const createNewSessionBinding = async (
+      sessionConfig: RunnerConfig,
+    ): Promise<OwnedSessionBinding<TuiProjectionStore>> => {
+      const freshProjectionStore = new TuiProjectionStore({
+        sessionId: sessionConfig.sessionId,
+        modelName: sessionConfig.modelName,
+        workspaceRoot,
+      });
+      const runtimeSession = await createSessionForConfig(
+        sessionConfig,
+        "new",
+        sessionConfig.sessionId,
+        freshProjectionStore,
+      );
+      return createLocalSessionBinding({
+        runtimeSession,
+        modelName: sessionConfig.modelName,
+        workspaceRoot,
+        profileName: sessionConfig.profileName,
+        projectionStore: freshProjectionStore,
+      });
+    };
+
+    const createSessionWithProfile = async (
+      profile: ClientModelProfile,
+    ): Promise<OwnedSessionBinding<TuiProjectionStore>> => {
+      if (profiles === undefined) {
+        throw new Error("Model profiles are not configured.");
+      }
+      return createNewSessionBinding(
+        deriveRunnerConfig(options.publicConfig, {
+          sessionId: createUuidV7() as SessionId,
+          profileName: profile.name,
+        }),
+      );
+    };
+
+    const createFreshSession = async (
+      current: SessionClient<TuiProjectionStore>,
+    ): Promise<OwnedSessionBinding<TuiProjectionStore>> => {
+      const sessionId = createUuidV7() as SessionId;
+      if (profiles === undefined) {
+        return createNewSessionBinding(
+          deriveRunnerConfig(options.publicConfig, { sessionId }),
+        );
+      }
+      if (current.profileName === undefined) {
+        throw new Error("Current session does not have a model profile.");
+      }
+      return createNewSessionBinding(
+        deriveRunnerConfig(options.publicConfig, {
+          sessionId,
+          profileName: current.profileName,
+        }),
+      );
+    };
+
+    const client = new LocalWorkspaceClient(
+      createLocalSessionBinding({
+        runtimeSession: initialSession,
+        modelName: config.modelName,
+        workspaceRoot,
+        profileName: config.profileName,
+        projectionStore,
+      }),
+      catalog,
+      openStoredSession,
+      createSessionWithProfile,
+      createFreshSession,
+    );
+    return {
+      client,
+      // Transitional local ownership retains today's exit cleanup policy.
+      close: (reason) =>
+        client.dispose(
+          reason.type === "client_exit"
+            ? { type: "tui_exit" }
+            : { type: "runner_failed", error: reason.error },
+        ),
+    };
+  } catch (error) {
+    await initialSession
+      .dispose({ type: "initialization_failed", error: errorMessage(error) })
+      .catch(() => undefined);
+    throw error;
+  }
+}
+
+class DeferredProjectionSink implements EventSink, AssistantTextDeltaSink {
+  readonly name = "deferred-tui-projection";
+  private target?: TuiProjectionStore;
+  private readonly buffered: AgentEvent[] = [];
+
+  async append(event: AgentEvent): Promise<void> {
+    if (this.target === undefined) {
+      this.buffered.push(event);
+      return;
+    }
+    await this.target.append(event);
+  }
+
+  updateAssistantTextDelta(update: AssistantTextDeltaUpdate): void {
+    this.target?.updateAssistantTextDelta(update);
+  }
+
+  async attach(target: TuiProjectionStore): Promise<void> {
+    if (this.target !== undefined) {
+      throw new Error("Deferred projection sink is already attached.");
+    }
+    this.target = target;
+    for (const event of this.buffered) {
+      await target.append(event);
+    }
+    this.buffered.length = 0;
+  }
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/cli/main.ts

@@ -90,6 +90,7 @@ export type MainDependencies = {
     input: { readonly stdin: PromptReadable; readonly cwd: string },
   ) => Promise<ResolvedPrompt>;
   readonly loadTuiRunner: () => Promise<TuiRunner>;
+  readonly loadDefaultTuiRunner: () => Promise<typeof import("./default-tui-runner")>;
   readonly loadOneShotRunner: () => Promise<OneShotRunner>;
   readonly loadUpdateRunner: () => Promise<UpdateRunner>;
   readonly loadServeRunner: () => Promise<typeof import("./serve-runner")>;
@@ -103,6 +104,7 @@ const DEFAULT_DEPENDENCIES: MainDependencies = {
   createSessionId: () => createUuidV7() as SessionId,
   resolvePromptSource,
   loadTuiRunner: () => import("./tui-runner"),
+  loadDefaultTuiRunner: () => import("./default-tui-runner"),
   loadOneShotRunner: () => import("./run-runner"),
   loadUpdateRunner: () => import("./update-runner"),
   loadServeRunner: () => import("./serve-runner"),
@@ -167,15 +169,33 @@ export async function main(
 
     if (parsed.command.type === "serve" || parsed.command.type === "connect") {
       const options = {
-        configPath: path.resolve(cwd, parsed.command.configPath),
+        ...(parsed.command.configPath === undefined
+          ? {}
+          : { configPath: path.resolve(cwd, parsed.command.configPath) }),
         env,
         stdout: input.stdout,
       };
       try {
         const exitCode =
           parsed.command.type === "serve"
-            ? await (await dependencies.loadServeRunner()).runServe(options)
-            : await (await dependencies.loadConnectRunner()).runConnect(options);
+            ? await (await dependencies.loadServeRunner()).runServe({
+                ...parsed.command,
+                ...options,
+              })
+            : await (await dependencies.loadConnectRunner()).runConnect({
+                ...parsed.command,
+                ...options,
+                configPath: path.resolve(cwd, parsed.command.configPath),
+                cwd,
+                ...(parsed.command.serviceConfigPath === undefined
+                  ? {}
+                  : {
+                      serviceConfigPath: path.resolve(
+                        cwd,
+                        parsed.command.serviceConfigPath,
+                      ),
+                    }),
+              });
         return finish(exitCode);
       } catch (error) {
         await writeCliOutput(
@@ -186,6 +206,29 @@ export async function main(
       }
     }
 
+    if (parsed.command.type === "tui" && !parsed.command.local) {
+      try {
+        const runner = await dependencies.loadDefaultTuiRunner();
+        return finish(
+          await runner.runDefaultTui({
+            cwd,
+            env,
+            stdout: input.stdout,
+            profileName: parsed.command.profileName,
+          }),
+        );
+      } catch (error) {
+        await writeCliOutput(
+          input.stderr,
+          renderCliFailure(
+            "Local service connection failed (use --local for independent execution)",
+            error,
+          ),
+        );
+        return finish(1);
+      }
+    }
+
     let configBoundary: ConfigBoundary;
     let publicConfig: ResolvedPublicConfig;
     let runnerConfig: RunnerConfig;

package/src/cli/public-cli-contract.ts

@@ -44,21 +44,84 @@ export const PUBLIC_CLI_CONTRACT = Object.freeze({
     description: "display help for command",
   }),
   tui: Object.freeze({
-    description: "Start the interactive terminal interface.",
+    description:
+      "Start the full TUI through the shared local service; exiting detaches only.",
+    localOption: Object.freeze({
+      flags: "--local",
+      description: "Run the TUI independently without a service (explicit fallback).",
+    } satisfies PublicCliOption),
     profileOption: PROFILE_OPTION,
   }),
   serve: Object.freeze({
+    residentOptions: Object.freeze([
+      {
+        flags: "--install",
+        description:
+          "Install and start a macOS per-user LaunchAgent with crash restart.",
+      },
+      {
+        flags: "--uninstall",
+        description:
+          "Drain, stop and remove the LaunchAgent; retain history and configuration.",
+      },
+      {
+        flags: "--stop",
+        description:
+          "Drain and stop the service; disable supervisor restart until the next start.",
+      },
+      {
+        flags: "--restart",
+        description: "Drain and restart with the current executable and configuration.",
+      },
+      {
+        flags: "--force",
+        description: "Allow interruption after the configured shutdown grace period.",
+      },
+    ] satisfies readonly PublicCliOption[]),
     command: "serve",
     description: "Run the local daemon for paired remote clients.",
     configOption: Object.freeze({
       flags: "--config <path>",
-      description: "Read the service JSON configuration.",
+      description:
+        "Read service JSON (default: <home>/.tinker/service/service.json; home follows TINKER_HOME).",
       valueName: "path",
     } satisfies PublicCliOption),
+    backgroundOption: Object.freeze({
+      flags: "--background",
+      description:
+        "Discover or start one detached service for this state directory, and print its address as JSON.",
+    } satisfies PublicCliOption),
+    statusOption: Object.freeze({
+      flags: "--status",
+      description:
+        "Probe the local service without starting it; print JSON and exit 1 when offline.",
+    } satisfies PublicCliOption),
   }),
   connect: Object.freeze({
     command: "connect",
     description: "Attach a terminal client to a service; exiting detaches only.",
+    tuiOption: Object.freeze({
+      flags: "--tui",
+      description: "Use the full TUI for service sessions and task execution.",
+    } satisfies PublicCliOption),
+    workspaceOption: Object.freeze({
+      flags: "--workspace <id>",
+      description:
+        "Select a service workspace for --tui; otherwise resolve the current directory on the service host.",
+      valueName: "id",
+    } satisfies PublicCliOption),
+    serviceConfigOption: Object.freeze({
+      flags: "--service-config <path>",
+      description:
+        "With --tui, discover/start this local service and register the current directory if needed.",
+      valueName: "path",
+    } satisfies PublicCliOption),
+    sessionOption: Object.freeze({
+      flags: "--session <id>",
+      description:
+        "Connect an existing session with --tui; otherwise create a new one.",
+      valueName: "id",
+    } satisfies PublicCliOption),
     configOption: Object.freeze({
       flags: "--config <path>",
       description: "Read the paired client JSON configuration.",

package/src/cli/public-config-contract.ts

@@ -605,7 +605,7 @@ function optionalRawString(value: string | undefined): string | undefined {
   return normalized === undefined || normalized === "" ? undefined : normalized;
 }
 
-function resolveUserPath(cwd: string, value: string): string {
+export function resolveUserPath(cwd: string, value: string): string {
   let expanded = value;
   if (value === "~") {
     expanded = os.homedir();