Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

61.2 KB
Raw Blame
import type { AdminToolAccess } from "./admin.ts";
import { parkedOutputKey, type ToolOutputStore } from "../sessions/tool-output.ts";
import { rankedSkills } from "../skills/materialize.ts";
import type { SkillResolution } from "../skills/skill-store.ts";
import {
  prepareExecutionFiles,
  processCredentialFiles,
  type ExecutionFileCredential,
} from "../credentials/execute-files.ts";
import type { MemoryCaptureMetadata } from "../memory/facts.ts";
import { disclosedMemory } from "../memory/disclosure.ts";
import { MaskedExecutionError, executionSecretEnv, createExactSecretValueMasker } from "../security/secret-masking.ts";
import { withAbort, withTimeout } from "../util/async.ts";
import type { RuntimeRequest, RuntimeResult } from "../harness/runtime-types.ts";
import { readContextFile } from "../resolution/context-files.ts";
import { type TurnContext } from "../resolution/turn-context.ts";
import { canReadNotebook, readNotebook, searchNotebooks } from "../memory/cross-scope.ts";
import type { SandboxAccessPlan, SandboxResource, SandboxResources } from "../sandbox/sandbox-resources.ts";
import { join } from "node:path";
import { workspacePathOf } from "../sandbox/exec-file-ops.ts";
import { interpolateSplitEnv } from "../deployment/deployment-layer.ts";
import type { CredentialPathSpec } from "../credentials/resident-paths.ts";
import type { ComputerStatus, ExecResult, Sandbox, SandboxHandle } from "../sandbox/sandbox.ts";
import { CapabilityUnsupportedError, hasParentPathSegment, supportsAgentComputerExport } from "../sandbox/sandbox.ts";
import type {
  ApprovalGrantModes,
  ClientToolResult,
  CommandPolicy,
  CommandRule,
  ConversationKind,
  GrantedHandle,
  Permission,
  Principal,
  ScopeId,
  WorkspaceLayer,
} from "../types.ts";
import { parseScopeId, scopeId } from "../types.ts";
import { type PublishAudienceKind } from "../resolution/publish-audience.ts";
import type { WorkspaceStore } from "../workspace/workspace-store.ts";
import type { BotPolicy } from "../surface-cache/channel-policy-store.ts";
import type { GapPhase, GapWork } from "../sessions/session-store.ts";
import type { SessionSyscalls } from "../sessions/session-syscalls.ts";
import { evaluateCommandWithLayer } from "../policy/command-policy.ts";
import { createNullLedger, type ToolLedger } from "../runs/tool-ledger.ts";
import { waitForClientResult, type RunSignalStore } from "../runs/run-signal-store.ts";
import type {
  BackgroundCredentials,
  BackgroundExecBroker,
  BackgroundStartResult,
  BackgroundPollResult,
  BackgroundStopResult,
  BackgroundWriteResult,
  BackgroundJobSummary,
} from "../connectors/background-exec-broker.ts";
import type { MonitorBroker, BackgroundWatchResult, BackgroundUnwatchResult } from "../monitors/monitor-broker.ts";
import { deploymentEntrypoint, type DeployService, type DeployFile } from "../deploy/deploy-service.ts";
import { publicUrlOf } from "../deploy/deploy-store.ts";
import { carriesGitMetadata } from "../deploy/deploy-fs.ts";
import type { AclStore } from "../acl/acl-store.ts";
import type { AuditLog } from "../audit/audit-log.ts";
import { TURN_FILES_DIR, type OutboundFile } from "../core/attachments.ts";
import { errMessage, withCleanup } from "../util/errors.ts";
import type { FileArtifactStore } from "../files/file-artifact-store.ts";
import type { ScopedConfigStore } from "../resolution/config-store.ts";
import { MEMORY_FILE, type MemoryEdit, type MemoryService } from "../memory/memory-service.ts";
import type { McpToolService } from "../mcp/mcp-tool-service.ts";
import type { ReachResolution } from "../resolution/scope-reach.ts";
import type {
  ControlService,
  CronCreateRequest,
  CronCreateResult,
  CronPatchRequest,
  CronRunsRequest,
  CronRunsResult,
  WebhookCreateRequest,
  WebhookCreateResult,
  ControlOk,
  ControlErr,
} from "../api/control-service.ts";
import type { ShareArtifactRequest, ShareArtifactResult } from "../api/artifact-share.ts";
import type { Cron, Webhook } from "../types.ts";
import type { CapabilityClaims } from "../auth/capability-token.ts";
import type { VisibleCron } from "../api/app.ts";
import { createPlaygroundArtifact, type PlaygroundArtifact } from "../playgrounds/playground.ts";

export interface PublishInput {
  dir?: string;
  entrypoint?: string;
  name?: string;
  renameFrom?: string;
  env?: Record<string, string>;
  rollbackTo?: number;
  alwaysOn?: boolean;
  embedAncestors?: string[];
  public?: boolean;
  share?: Array<{ scope: ScopeId; permission: Permission }>;
  sandboxId?: string;
}

export interface PublishAudienceDescriptor {
  kind: PublishAudienceKind;
  orgId?: string;
  channelRef?: string;
  memberCount?: number;
  snapshotAt?: number;
  note?: string;
}

interface PublishResult {
  id: string;
  name?: string;
  version: number;
  url: string;
  audience?: PublishAudienceDescriptor;
  dataDir?: string;
  alwaysOn?: boolean;
  embedAncestors?: string[];
  public?: boolean;
}

export class NeedsApproval extends Error {
  command: string;
  approvalReason: string;
  kind: "approval";
  matched?: string;
  approvalKey?: string;
  grantModes?: ApprovalGrantModes;
  constructor(
    command: string,
    reason: string,
    kind: "approval" = "approval",
    matched?: string,
    approvalKey?: string,
    grantModes?: ApprovalGrantModes,
  ) {
    super(`command requires approval: ${command}`);
    this.name = "NeedsApproval";
    this.command = command;
    this.approvalReason = reason;
    this.kind = kind;
    this.matched = matched;
    this.approvalKey = approvalKey;
    this.grantModes = grantModes;
  }
}

export class CommandDenied extends Error {
  constructor(command: string, reason: string) {
    super(`command denied (${reason}): ${command}`);
    this.name = "CommandDenied";
  }
}

interface ReadResult {
  content: string | null;
  sourceScopeId: ScopeId | null;
  shared?: true;
  outsideWorkspace?: true;
}

export interface SkillResult {
  content: string | null;
  sourceScopeId: ScopeId | null;
  dir?: string;
  packDir?: string;
}

interface ReachedProvenance {
  scopeId: ScopeId;
  label: string;
}

export interface CommandCredential {
  handle: string;
  scope?: "scoped" | "owner";
  env?: Array<{ key: string; value: string; secret?: boolean }>;
  resolve?: () => Promise<{
    commit?: () => Promise<void>;
    singleUse?: boolean;
    files?: ExecutionFileCredential;
    env: Array<{ key: string; value: string; secret?: boolean }>;
  }>;
}

interface AttachedFileMeta {
  name: string;
  mimetype: string;
  sizeBytes: number;
  artifactId?: string;
}

export type AttachResult = { ok: true; files: AttachedFileMeta[]; staged: number } | { ok: false; message: string };

export type AttachFiles = (files: readonly OutboundFile[], sandboxId?: string) => Promise<AttachResult>;

export interface ToolContext extends SurfaceToolDeps {
  installSharedCanvas?: (fileId: string) => Promise<string | null>;
  admin?: AdminToolAccess;
  runtime?(request: RuntimeRequest, signal?: AbortSignal): Promise<RuntimeResult>;
  attach: AttachFiles;
  sessionSyscalls?: SessionSyscalls;
  /** True when a person's own message started this turn (not a cron, webhook, ambient or delegated wake). */
  humanTurn?: boolean;
  toolOutput?: Pick<ToolOutputStore, "inlineTokens" | "save">;
  commandCredentialHandles?: readonly string[];
  execute(
    command: string,
    opts?: {
      timeoutSeconds?: number;
      sandboxId?: string;
      scratch?: boolean;
      ownerAuth?: boolean;
      reachTarget?: string;
      signal?: AbortSignal;
      credentials?: string[];
    },
  ): Promise<ExecResult & { reached?: ReachedProvenance }>;
  sandboxResources?(
    action: "list" | "create" | "default" | "retire",
    input?: { backend?: string; name?: string; sandboxId?: string | null },
  ): Promise<unknown>;
  computerStatus(sandboxId?: string): Promise<ComputerStatus>;
  restartComputer(sandboxId?: string): Promise<void>;
  read(path: string, signal?: AbortSignal, sandboxId?: string): Promise<ReadResult>;
  listSkills(
    query?: string,
    offset?: number,
    limit?: number,
    source?: string,
  ): Promise<{
    sourceScopeId: ScopeId | null;
    skills: Array<{ name: string; description: string; source?: string }>;
    nextOffset?: number;
  }>;
  skill(
    name: string,
    opts?: { path?: string; sandboxId?: string; source?: string; signal?: AbortSignal },
  ): Promise<SkillResult>;
  write(path: string, data: string, sandboxId?: string): Promise<void>;
  publish(input: PublishInput): Promise<PublishResult>;
  setDeploymentPublic(id: string, isPublic: boolean): Promise<{ id: string; name?: string; public: boolean }>;
  createPlayground(input: { title: string; html: string }): Promise<PlaygroundArtifact>;
  memorySearch(q: string, limit?: number, scope?: ScopeId): Promise<string[] | null>;
  memoryRead(scope?: ScopeId): Promise<string | null>;
  memoryAdd(facts: string[]): Promise<number | null>;
  memoryEdit(edits: MemoryEdit[]): Promise<true | null>;
  memoryDelete(ids: string[]): Promise<true | null>;
  history(q: string, limit?: number): Promise<string[]>;
  historyOpen(seq: number): Promise<string | null>;
  callMcpTool(name: string, args: Record<string, unknown>, approval?: string): Promise<string>;
  mcpToolNeedsApproval(name: string, args: Record<string, unknown>): Promise<boolean>;
  awaitClientResult(
    callId: string,
    timeoutMs: number,
    signal?: AbortSignal,
    toolName?: string,
  ): Promise<ClientToolResult | "timeout" | "cancelled">;
  backgroundStart(
    command: string,
    opts: { purpose: string; ttlSeconds?: number; sandboxId?: string; credentials?: string[] },
  ): Promise<BackgroundStartResult>;
  backgroundPoll(
    processId: string,
    opts?: { sinceCursor?: number; maxBytes?: number; waitSeconds?: number },
  ): Promise<BackgroundPollResult>;
  backgroundStop(processId: string, signal?: string): Promise<BackgroundStopResult>;
  backgroundWrite(processId: string, data: string): Promise<BackgroundWriteResult>;
  backgroundList(): Promise<BackgroundJobSummary[]>;
  backgroundWatch(
    processId: string,
    opts?: { instructions?: string; pattern?: string; sinceCursor?: number },
  ): Promise<BackgroundWatchResult>;
  backgroundUnwatch(monitorId: string): Promise<BackgroundUnwatchResult>;
  cronCreate(req: CronCreateRequest): Promise<CronCreateResult | ControlUnavailable>;
  cronList(): Promise<{ crons: Cron[]; visible: VisibleCron[] } | ControlUnavailable>;
  cronGet(id: string): Promise<ControlOk<{ cron: Cron }> | ControlErr<"not_found" | "forbidden"> | ControlUnavailable>;
  cronRuns(
    id: string,
    req?: CronRunsRequest,
  ): Promise<ControlOk<CronRunsResult> | ControlErr<"not_found" | "forbidden" | "bad_request"> | ControlUnavailable>;
  cronPatch(
    id: string,
    req: CronPatchRequest,
  ): Promise<
    | ControlOk<{ cron: Cron }>
    | ControlErr<"not_found" | "forbidden" | "bad_request" | "cron_update_failed">
    | ControlUnavailable
  >;
  cronNote(
    id: string,
    note: string,
  ): Promise<
    ControlOk<{ applied: boolean }> | ControlErr<"not_found" | "forbidden" | "bad_request"> | ControlUnavailable
  >;
  cronDelete(
    id: string,
  ): Promise<ControlOk<Record<never, never>> | ControlErr<"not_found" | "forbidden"> | ControlUnavailable>;
  cronSetEnabled(
    id: string,
    enabled: boolean,
  ): Promise<ControlOk<{ cron: Cron }> | ControlErr<"not_found" | "forbidden"> | ControlUnavailable>;
  cronRun(
    id: string,
  ): Promise<
    | ControlOk<{ fireKey: string }>
    | ControlErr<"not_found" | "forbidden" | "unavailable" | "bad_request" | "already_running">
    | ControlUnavailable
  >;
  cronRetarget(
    id: string,
    destinationKey: string,
  ): Promise<
    ControlOk<{ cron: Cron }> | ControlErr<"not_found" | "forbidden" | "unknown_destination"> | ControlUnavailable
  >;
  webhookCreate(req: WebhookCreateRequest): Promise<WebhookCreateResult | ControlUnavailable>;
  webhookList(): Promise<Webhook[] | ControlUnavailable>;
  webhookDisable(
    id: string,
  ): Promise<ControlOk<Record<never, never>> | ControlErr<"not_found" | "forbidden"> | ControlUnavailable>;
  webhookUpdate(
    id: string,
    action: string,
  ): Promise<
    ControlOk<{ webhook: Webhook }> | ControlErr<"not_found" | "forbidden" | "bad_request"> | ControlUnavailable
  >;
  soulRead(): { effectiveSoul: string; soul: string | null; soulVersion: number } | ControlUnavailable;
  soulWrite(
    content: string,
    expectedVersion?: number,
  ): Promise<
    | ControlOk<{ version: number }>
    | ControlErr<"soul_update_denied" | "soul_version_conflict" | "soul_update_failed">
    | ControlUnavailable
  >;
  shareArtifact(req: ShareArtifactRequest): Promise<ShareArtifactResult | ControlUnavailable>;
}

interface SurfaceSearchToolOpts {
  limit?: number;
  source?: "mirror" | "slack";
}

interface SurfacePostOpts {
  ts?: string;
  broadcast?: boolean;
}

interface SurfaceReachTarget {
  channel?: string;
  recipient?: string;
  participants?: readonly string[];
}

export interface SurfaceReactInput {
  ts: string;
  emoji: string;
  channel?: string;
  participants?: readonly string[];
}

export interface SurfaceEditInput {
  ref: string;
  text: string;
  channel?: string;
  participants?: readonly string[];
}

export interface SurfaceDeleteInput {
  ref: string;
  channel?: string;
  participants?: readonly string[];
}

export interface PostedFileMeta {
  name: string;
  mimetype: string;
  sizeBytes: number;
  artifactId?: string;
}

export interface SurfacePostResult {
  ok: boolean;
  deliveryId?: string;
  message?: string;
  matched?: string;
  attachments?: PostedFileMeta[];
}

interface SurfaceReadResult {
  ok: boolean;
  messages?: unknown[];
  message?: string;
}

interface SurfaceWhatsNewResult {
  ok: boolean;
  hereNew?: number;
  activeSubConversations?: number;
  latest?: string;
  coverageSince?: string;
  message?: string;
}

interface SurfaceSearchHit {
  ref?: string;
  author?: string;
  when?: string;
  snippet: string;
}
export interface SurfaceSearchResult {
  ok: boolean;
  hits?: SurfaceSearchHit[];
  source?: "cache" | "live" | "slack";
  coverageSince?: string;
  message?: string;
}

interface SurfaceMembersResult {
  ok: boolean;
  members?: Array<{ displayName: string }>;
  message?: string;
}

interface SurfaceFileResult {
  ok: boolean;
  content?: string;
  name?: string;
  sizeBytes?: number;
  contentType?: string;
  message?: string;
}

type SurfaceStandingOrderResult =
  | { ok: true; orders: string; bots?: Record<string, BotPolicy>; ambientEnabled?: boolean }
  | { ok: false; message: string };

export interface SurfaceToolDeps {
  post(
    text: string,
    opts?: SurfacePostOpts,
    files?: readonly OutboundFile[],
    sandboxId?: string,
  ): Promise<SurfacePostResult>;
  reach(
    text: string,
    target: SurfaceReachTarget,
    files?: readonly OutboundFile[],
    sandboxId?: string,
  ): Promise<SurfacePostResult>;
  react(input: SurfaceReactInput): Promise<SurfacePostResult>;
  edit(input: SurfaceEditInput): Promise<SurfacePostResult>;
  delete(input: SurfaceDeleteInput): Promise<SurfacePostResult>;
  readThread(opts?: { limit?: number }): Promise<SurfaceReadResult>;
  whatsNew(opts?: { since?: string }): Promise<SurfaceWhatsNewResult>;
  search(query: string, opts?: SurfaceSearchToolOpts): Promise<SurfaceSearchResult>;
  readMembers(): Promise<SurfaceMembersResult>;
  readFile(ref: string): Promise<SurfaceFileResult>;
  getStandingOrder(): Promise<SurfaceStandingOrderResult>;
  setStandingOrder(
    orders: string | undefined,
    bots?: Record<string, BotPolicy>,
    ambientEnabled?: boolean | null,
    expectedOrders?: string,
  ): Promise<SurfaceStandingOrderResult>;
}

export interface ControlUnavailable {
  ok: false;
  code: "control_unavailable";
  message: string;
}
export const CONTROL_UNAVAILABLE: ControlUnavailable = {
  ok: false,
  code: "control_unavailable",
  message: "the control plane (crons, webhooks, standing instructions) isn't available on this turn",
};

export interface ToolContextDeps {
  desktopClientId?: string;
  admin?: AdminToolAccess;
  installSharedCanvas?: (fileId: string) => Promise<string | null>;
  sandbox: Sandbox;
  commandCredentials?: readonly CommandCredential[];
  resolveCommandCredentials?: (handles: readonly string[]) => Promise<readonly CommandCredential[]>;
  provision: () => Promise<SandboxHandle>;
  provisionScratch?: () => Promise<SandboxHandle>;
  provisionResource?: (
    input: string | SandboxAccessPlan,
    authorize?: (access: SandboxAccessPlan) => void,
  ) => Promise<SandboxHandle>;
  accessSandboxResource?: (id: string) => Promise<SandboxAccessPlan>;
  provisionOwnerAuth?: () => Promise<SandboxHandle>;
  ownerAuthCommand?: (command: string, env?: Record<string, string>) => string;
  listSkills?: (source?: string) => Promise<SkillResolution[]>;
  useSkill?: (name: string, path: string, sandboxId?: string, source?: string) => Promise<SkillResult>;
  reach?: {
    resolveChannel(query: string): Promise<ReachResolution>;
    provisionFor(scopeId: ScopeId): Promise<SandboxHandle>;
  };
  layers: WorkspaceLayer[];
  commandPolicy: () => CommandPolicy;
  layerCommandRules?: () => readonly CommandRule[];
  authorizeCommand: (command: string, approvalKey?: string, exactApprovalKey?: boolean) => boolean;
  grantedHandles: GrantedHandle[];
  context?: TurnContext;
  sandboxResources?: SandboxResources;
  invalidateProvision?: () => void;
  workspace: WorkspaceStore;
  deploy: DeployService;
  acl: AclStore;
  files?: FileArtifactStore;
  auditLog?: AuditLog;
  createdBy: string;
  publicWebUrl?: string;
  publishContext?: {
    conversationKind: ConversationKind;
    channelRef?: string;
    isPrivate?: boolean;
    isMpim?: boolean;
    publishMembers?: Principal[];
  };
  config?: ScopedConfigStore;
  memory?: MemoryService;
  memoryScopeId?: ScopeId;
  memoryCaptureMetadata?: () => MemoryCaptureMetadata;
  memoryAccess?: { write?: ScopeId; read: ScopeId[] };
  mcp?: McpToolService;
  sessionHistory?: {
    search(q: string, limit?: number): Promise<string[]>;
    open(seq: number): Promise<string | null>;
  };
  actingSlackUserId?: string;
  layerAuth?: {
    credentialPaths: readonly CredentialPathSpec[];
    splitEnvTemplates: ReadonlyArray<Record<string, string>>;
  };
  execTimeoutMs?: number;
  execTimeoutCeilingMs?: number;
  ledger?: ToolLedger;
  signals?: RunSignalStore;
  runId?: string;
  attempt?: number;
  backgroundBroker?: BackgroundExecBroker;
  monitorBroker?: MonitorBroker;
  onGapWork?: (work: GapWork) => void;
  control?: ControlService;
  controlClaims?: CapabilityClaims;
  webhookPublicUrl?: string;
  surface?: SurfaceToolDeps;
  attach?: AttachFiles;
  sessionSyscalls?: SessionSyscalls;
  humanTurn?: boolean;
  toolOutput?: ToolOutputStore;
  sessionId?: string;
}

export function createToolContext(deps: ToolContextDeps): ToolContext {
  const writableScopeId = deps.layers.find((l) => l.mode === "rw")?.scopeId ?? null;
  const memory =
    deps.context?.memory ??
    (deps.memory
      ? disclosedMemory(deps.memory, {
          actor: { id: deps.createdBy, type: "internal" },
          targetScope: writableScopeId ?? `personal:${deps.createdBy}`,
          nativeScopes: [
            ...deps.layers.map((layer) => layer.scopeId),
            ...(deps.memoryAccess?.read ?? []).filter((scope) => scope.startsWith("org:")),
          ],
          audience: deps.publishContext?.publishMembers ?? [{ id: deps.createdBy, type: "internal" }],
          open: false,
        })
      : undefined);
  const fallbackMounts = deps.layers.filter((l) => l.mode === "ro" && l.mountPath);
  const persistExclude = [...fallbackMounts.map((mount) => mount.mountPath!), TURN_FILES_DIR];

  const accessSandbox = async (id: string): Promise<SandboxAccessPlan> => {
    if (!deps.sandboxResources || !deps.accessSandboxResource) throw new Error("sandbox inventory unavailable");
    if (!id.trim()) throw new Error("sandbox_id must name a sandbox; omit it to use the default");
    return deps.accessSandboxResource(id);
  };

  const machine = async (
    id: string | undefined,
  ): Promise<{
    handle: SandboxHandle;
    resource?: SandboxResource;
    crossScope: boolean;
    durableRef: (path: string) => string;
  }> => {
    if (id === undefined) {
      const handle = await deps.provision();
      const resource = handle.resourceId ? await deps.sandboxResources?.get(handle.resourceId) : undefined;
      return { handle, ...(resource ? { resource } : {}), crossScope: false, durableRef: (path) => path };
    }
    let access = await accessSandbox(id);
    if (!deps.provisionResource) throw new Error("sandbox inventory unavailable");
    const handle = await deps.provisionResource(access, (current) => {
      access = current;
    });
    const resource = access.resource;
    const fallback = writableScopeId ? await deps.sandboxResources!.resolve(writableScopeId) : null;
    const durableRef =
      fallback?.id === resource.id ? (path: string) => path : (path: string) => `sandbox-files/${resource.id}/${path}`;
    return { handle, resource, crossScope: access.crossScope, durableRef };
  };

  const authorizeExecution = (command: string, access?: SandboxAccessPlan, policy = deps.commandPolicy()): void => {
    const source = evaluateCommandWithLayer(command, policy, deps.layerCommandRules?.() ?? []);
    if (source.decision === "deny") throw new CommandDenied(command, source.reason ?? "denied by policy");
    if (!access?.crossScope) {
      if (source.decision === "require_approval" && !deps.authorizeCommand(command, source.approvalKey))
        throw new NeedsApproval(
          command,
          source.reason ?? "requires approval",
          "approval",
          source.matched,
          source.approvalKey,
        );
      return;
    }
    const target = access.commandPolicy
      ? evaluateCommandWithLayer(command, access.commandPolicy, [])
      : { decision: "allow" as const };
    if (target.decision === "deny")
      throw new CommandDenied(command, target.reason ?? "denied by target sandbox policy");
    if (source.decision !== "require_approval" && target.decision !== "require_approval") return;
    const approvalKey = `sandbox:${JSON.stringify([
      access.resource.ownerScopeId,
      source.approvalKey ?? command,
      target.approvalKey ?? command,
    ])}`;
    const required = target.decision === "require_approval" ? target : source;
    const grantModes = { session: false, always: false };
    if (!deps.authorizeCommand(command, approvalKey, true))
      throw new NeedsApproval(
        command,
        required.reason ?? "requires sandbox approval",
        "approval",
        required.matched,
        approvalKey,
        grantModes,
      );
  };

  const ledger = deps.ledger ?? createNullLedger();
  const runId = deps.runId;
  const attempt = deps.attempt ?? 1;
  let callIndex = -1;

  async function timed<T>(phase: GapPhase, op: () => Promise<T>): Promise<T> {
    const start = Date.now();
    try {
      return await op();
    } finally {
      try {
        deps.onGapWork?.({ phase, start, end: Date.now() });
      } catch (error) {
        void error;
      }
    }
  }

  async function once<T>(produce: () => Promise<T>, shouldCache: (r: T) => boolean = () => true): Promise<T> {
    const index = ++callIndex;
    if (runId === undefined) return produce();
    const prior = await timed("tool_ledger", () => ledger.begin(runId, attempt, index));
    if (prior.cached) return JSON.parse(prior.output ?? "null") as T;
    const result = await produce();
    if (shouldCache(result))
      await timed("tool_ledger", () => ledger.record(runId, attempt, index, JSON.stringify(result ?? null)));
    return result;
  }

  function controlOp<R>(
    run: (control: ControlService, claims: CapabilityClaims) => Promise<R>,
    cache?: (r: R) => boolean,
  ): Promise<R | ControlUnavailable> {
    if (!deps.control || !deps.controlClaims) return Promise.resolve(CONTROL_UNAVAILABLE);
    const call = () => run(deps.control!, deps.controlClaims!);
    return cache ? once(call, cache) : call();
  }

  function surfaceOp<R>(
    run: (surface: SurfaceToolDeps) => Promise<R>,
    cache?: (r: R) => boolean,
  ): Promise<R | { ok: false; message: string }> {
    if (!deps.surface) return Promise.resolve({ ok: false, message: SURFACE_UNAVAILABLE_MESSAGE });
    const call = () => run(deps.surface!);
    return cache ? once(call, cache) : call();
  }

  const selectCredentials = async (handles: readonly string[], ownerAuth: boolean) => {
    const available = new Map(
      (
        (handles.length ? await deps.resolveCommandCredentials?.(handles) : undefined) ??
        deps.commandCredentials ??
        []
      ).map((credential) => [credential.handle, credential] as const),
    );
    return handles.map((handle) => {
      const credential = available.get(handle);
      if (!credential) throw new Error(`credential handle is not available on this turn: ${handle}`);
      if ((credential.scope ?? "scoped") !== (ownerAuth ? "owner" : "scoped"))
        throw new Error(`credential ${handle} requires scope:${credential.scope ?? "scoped"}`);
      return credential;
    });
  };

  const stageCredentials = async (
    requested: readonly CommandCredential[],
    handle: SandboxHandle,
    use: "command" | "background",
    signal?: AbortSignal,
  ) => {
    const commandEnv: Record<string, string> = {};
    const prepared: Array<{
      commit?: () => Promise<void>;
      singleUse?: boolean;
      files?: ExecutionFileCredential;
      env: Array<{ key: string; value: string; secret?: boolean }>;
    }> = [];
    for (const credential of new Set(requested)) {
      const materialized = credential.resolve ? await credential.resolve() : { env: credential.env ?? [] };
      prepared.push(materialized);
      for (const { key, value } of materialized.env) {
        if (key in commandEnv && commandEnv[key] !== value)
          throw new Error(`requested credentials provide conflicting environment key: ${key}`);
        commandEnv[key] = value;
      }
      deps.auditLog?.record({
        at: Date.now(),
        principalId: deps.createdBy,
        action: "keychain.materialize",
        resource: `${credential.handle} (${use})`,
        scopeLabel: writableScopeId!,
      });
    }
    signal?.throwIfAborted();
    const singleUse = prepared.filter((credential) => credential.singleUse);
    if (singleUse.length > 1) throw new Error("An execution may use at most one single-use grant");
    for (const credential of prepared.filter((credential) => !credential.singleUse)) await credential.commit?.();
    signal?.throwIfAborted();
    for (const credential of singleUse) await credential.commit?.();
    const fileCredentials = prepared.flatMap((credential) => (credential.files ? [credential.files] : []));
    const fileExecution = fileCredentials.length
      ? await prepareExecutionFiles(deps.sandbox, handle, fileCredentials)
      : undefined;
    for (const [key, value] of Object.entries(fileExecution?.env ?? {})) {
      if (key in commandEnv && commandEnv[key] !== value) {
        await fileExecution!.finish();
        throw new Error(`requested credentials provide conflicting environment key: ${key}`);
      }
      commandEnv[key] = value;
    }
    return {
      commandEnv,
      secretValues: prepared.flatMap((credential) => credential.env),
      fileExecution,
      fileCredentials,
    };
  };

  return {
    ...(deps.admin ? { admin: deps.admin } : {}),
    ...(deps.installSharedCanvas ? { installSharedCanvas: deps.installSharedCanvas } : {}),
    ...(deps.toolOutput ? { toolOutput: deps.toolOutput } : {}),
    ...(deps.commandCredentials?.length
      ? { commandCredentialHandles: deps.commandCredentials.map((credential) => credential.handle) }
      : {}),
    ...(deps.sandboxResources && deps.accessSandboxResource
      ? {
          async sandboxResources(
            action: "list" | "create" | "default" | "retire",
            input?: { backend?: string; name?: string; sandboxId?: string | null },
          ): Promise<unknown> {
            if (!writableScopeId) throw new Error("sandbox management requires an owning scope");
            const resources = deps.sandboxResources!;
            if (action === "list") {
              const listed = await resources.list(deps.createdBy, writableScopeId);
              return {
                ...listed,
                sandboxes: (
                  await Promise.all(
                    listed.sandboxes.map(async (record) =>
                      deps.accessSandboxResource!(record.id)
                        .then((access) => access.resource)
                        .catch(() => null),
                    ),
                  )
                ).filter((record) => record !== null),
              };
            }
            if (action === "retire") {
              if (!input?.sandboxId) throw new Error("retire requires sandbox_id");
              const { resource } = await accessSandbox(input.sandboxId);
              await resources.retire(deps.createdBy, resource.id);
              return { retired: resource.id };
            }
            if (action === "default") {
              if (input?.sandboxId === undefined) throw new Error("default requires sandbox_id or null");
              await resources.setDefault(deps.createdBy, writableScopeId, input.sandboxId);
              deps.invalidateProvision?.();
              return { defaultSandboxId: input.sandboxId };
            }
            if (!input?.backend || !deps.provisionResource) throw new Error("create requires an available backend");
            const record = await resources.create(deps.createdBy, writableScopeId, input.backend, input.name);
            await deps.provisionResource(record.id);
            return record;
          },
        }
      : {}),
    async computerStatus(sandboxId?: string): Promise<ComputerStatus> {
      const probe = async (status: ComputerStatus, provision: () => Promise<SandboxHandle>) => {
        if (!status.provisioned || status.lifecycleState === "paused") return status;
        try {
          const code = await withTimeout(
            async () =>
              (await deps.sandbox.run(await provision(), "true", { timeoutMs: COMMAND_PATH_PROBE_TIMEOUT_MS })).code,
            COMMAND_PATH_PROBE_TIMEOUT_MS * 2,
            "command probe",
          );
          return { ...status, guestResponsive: code === 0 };
        } catch (e) {
          return { ...status, guestResponsive: false, probeError: errMessage(e) };
        }
      };
      if (sandboxId !== undefined) {
        const resources = deps.sandboxResources;
        if (!resources || !deps.provisionResource) throw new Error("sandbox inventory unavailable");
        const access = await accessSandbox(sandboxId);
        return probe(await resources.status(deps.createdBy, sandboxId), () => deps.provisionResource!(access));
      }
      if (!deps.sandbox.computerStatus) {
        throw new CapabilityUnsupportedError(deps.sandbox.profile.backend, "reporting computer status");
      }
      if (!writableScopeId) throw new Error("this turn has no scoped computer");
      return probe(await deps.sandbox.computerStatus(writableScopeId), deps.provision);
    },
    async restartComputer(sandboxId?: string): Promise<void> {
      if (sandboxId !== undefined) {
        const resources = deps.sandboxResources;
        if (!resources) throw new Error("sandbox inventory unavailable");
        await accessSandbox(sandboxId);
        return resources.restart(deps.createdBy, sandboxId);
      }
      if (!deps.sandbox.restartComputer) {
        throw new CapabilityUnsupportedError(deps.sandbox.profile.backend, "restarting the computer");
      }
      if (!writableScopeId) throw new Error("this turn has no scoped computer to restart");
      await deps.sandbox.restartComputer(writableScopeId);
    },
    async execute(
      command: string,
      execOpts?: {
        timeoutSeconds?: number;
        sandboxId?: string;
        scratch?: boolean;
        ownerAuth?: boolean;
        reachTarget?: string;
        signal?: AbortSignal;
        credentials?: string[];
      },
    ): Promise<ExecResult & { reached?: ReachedProvenance }> {
      return once(async () => {
        const scratch = execOpts?.scratch === true;
        const ownerAuth = execOpts?.ownerAuth === true;
        const requestedCredentials = execOpts?.credentials ?? [];
        if (requestedCredentials.length && (execOpts?.reachTarget !== undefined || !writableScopeId)) {
          throw new Error("command credentials are available only on scoped, scratch, or owner computers");
        }
        const requested = await selectCredentials(requestedCredentials, ownerAuth);
        const reachTarget = execOpts?.reachTarget;
        if (
          [scratch, ownerAuth, reachTarget !== undefined, execOpts?.sandboxId !== undefined].filter(Boolean).length > 1
        ) {
          throw new Error("a command runs on one computer — choose scoped, scratch, owner, or a reached room");
        }
        if (scratch && !deps.provisionScratch) {
          throw new Error('scratch execution is not available on this computer — run without scope:"scratch"');
        }
        if (ownerAuth && !deps.provisionOwnerAuth) {
          throw new Error('an owner-auth box is not available on this turn — use scope:"scoped"');
        }
        let reached: ReachedProvenance | undefined;
        if (reachTarget !== undefined) {
          if (!deps.reach) {
            throw new Error(
              "visiting another conversation's computer works from a DM — here, ask in that channel instead",
            );
          }
          const target = await deps.reach.resolveChannel(reachTarget);
          if (target.kind === "error") throw new Error(target.message);
          reached = { scopeId: target.scopeId, label: `#${target.channelName}` };
        }
        const executionPolicy = deps.commandPolicy;
        let handle;
        if (execOpts?.sandboxId !== undefined) {
          if (!deps.sandboxResources || !deps.provisionResource) throw new Error("sandbox inventory unavailable");
          const access = await accessSandbox(execOpts.sandboxId);
          handle = await deps.provisionResource(access, (current) => {
            if (current.crossScope && requestedCredentials.length)
              throw new Error("command credentials cannot be copied to another scope's computer");
            authorizeExecution(command, current, executionPolicy());
          });
        } else {
          authorizeExecution(command, undefined, executionPolicy());
          if (reached) handle = await deps.reach!.provisionFor(reached.scopeId);
          else if (scratch) handle = await deps.provisionScratch!();
          else if (ownerAuth) handle = await deps.provisionOwnerAuth!();
          else handle = await deps.provision();
        }
        const resolvedMs = execOpts?.timeoutSeconds != null ? execOpts.timeoutSeconds * 1000 : deps.execTimeoutMs;
        const timeoutMs =
          resolvedMs != null && deps.execTimeoutCeilingMs != null
            ? Math.min(resolvedMs, deps.execTimeoutCeilingMs)
            : resolvedMs;
        const opts =
          timeoutMs !== undefined || execOpts?.signal
            ? {
                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
                ...(execOpts?.signal ? { signal: execOpts.signal } : {}),
              }
            : undefined;
        if (reached) {
          deps.auditLog?.record({
            at: Date.now(),
            principalId: deps.createdBy,
            action: "reach_exec",
            resource: command,
            scopeLabel: reached.scopeId,
          });
        }
        return timed("exec", async () => {
          execOpts?.signal?.throwIfAborted();
          const { commandEnv, secretValues, fileExecution } = await stageCredentials(
            requested,
            handle,
            "command",
            execOpts?.signal,
          );
          const r = await withCleanup(
            async (): Promise<ExecResult> => {
              const sandboxCommand = ownerAuth ? (deps.ownerAuthCommand?.(command, commandEnv) ?? command) : command;
              const commandHandle = Object.keys(commandEnv).length
                ? { ...handle, env: { ...handle.env, ...commandEnv } }
                : handle;
              const secretEnv = executionSecretEnv(commandHandle.env, secretValues);
              const mask = createExactSecretValueMasker(Object.values(secretEnv));
              try {
                const result = await deps.sandbox.run(commandHandle, sandboxCommand, opts);
                return { ...result, stdout: mask(result.stdout), stderr: mask(result.stderr) };
              } catch (error) {
                const message = errMessage(error);
                const masked = mask(message);
                if (masked !== message) throw new MaskedExecutionError(error, mask, masked);
                throw error;
              }
            },
            async () => {
              await fileExecution?.finish();
            },
          );
          return reached ? { ...r, reached } : r;
        });
      });
    },

    async read(path: string, signal?: AbortSignal, sandboxId?: string): Promise<ReadResult> {
      signal?.throwIfAborted();
      if (path === MEMORY_FILE && memory && deps.memoryScopeId) {
        if (!deps.memoryAccess?.read.includes(deps.memoryScopeId)) {
          throw new Error("memory recall is not enabled for this conversation; use the `memory` tool when enabled");
        }
        const content = await withAbort(() => memory.read(deps.memoryScopeId!), signal);
        return { content, sourceScopeId: deps.memoryScopeId };
      }
      const sharedFile = deps.context
        ? await withAbort(() => deps.context!.readFile(path), signal)
        : await withAbort(() => readContextFile(path, deps.grantedHandles, deps.files), signal);
      if (sharedFile && "error" in sharedFile) return { content: sharedFile.error, sourceScopeId: null };
      if (sharedFile) {
        const { grant: granted, bytes } = sharedFile;
        if (bytes === null) return { content: null, sourceScopeId: granted.ownerScopeId };
        const asText = tryDecodeUtf8(bytes);
        if (asText !== null) return { content: asText, sourceScopeId: granted.ownerScopeId, shared: true };
        return {
          content: `[binary file ${granted.handlePath.split("/").pop()}, Files ID ${granted.fileId}; send it by ID]`,
          sourceScopeId: granted.ownerScopeId,
          shared: true,
        };
      }
      if (path.startsWith("shared/open-")) return { content: null, sourceScopeId: null };
      const parkedKey = parkedOutputKey(path);
      if (parkedKey && deps.toolOutput && deps.sessionId) {
        const parked = await withAbort(() => deps.toolOutput!.read(deps.sessionId!, parkedKey), signal);
        if (parked && "expired" in parked)
          return {
            content: `[the full output in ${path} expired after 30 days; only the cut shown in the transcript remains]`,
            sourceScopeId: writableScopeId,
          };
        if (parked) {
          const { handle } = await machine(sandboxId);
          await withAbort(() => deps.sandbox.writeFile(handle, path, parked.text), signal);
          return {
            content: `[copied the full output (${parked.text.length} chars) to ${path} on the computer; read the parts you need with execute, e.g. sed -n or grep]`,
            sourceScopeId: writableScopeId,
          };
        }
      }
      signal?.throwIfAborted();
      const { handle, resource, crossScope } = await machine(sandboxId);
      const mounts = crossScope ? fallbackMounts.filter((mount) => mount.mountPath === "global") : fallbackMounts;
      const rel = path.startsWith("/") ? workspacePathOf(handle.rootDir, path) : path;
      if (rel === null) return { content: null, sourceScopeId: null, outsideWorkspace: true };
      return timed("file_op", async () => {
        const direct = await withAbort(() => deps.sandbox.readFile(handle, rel), signal);
        if (direct !== null) return { content: direct, sourceScopeId: resource?.ownerScopeId ?? writableScopeId };
        for (const mount of mounts) {
          const v = await withAbort(() => deps.sandbox.readFile(handle, join(mount.mountPath, rel)), signal);
          if (v !== null) return { content: v, sourceScopeId: mount.scopeId };
        }
        return { content: null, sourceScopeId: null };
      });
    },

    async createPlayground(input: { title: string; html: string }): Promise<PlaygroundArtifact> {
      if (!deps.files || !writableScopeId) throw new Error("playgrounds require a writable artifact store");
      return once(() =>
        createPlaygroundArtifact(deps.files!, {
          ...input,
          ownerScopeId: writableScopeId,
          createdBy: deps.createdBy,
        }),
      );
    },

    async listSkills(query = "", offset = 0, limit = 50, source?: string) {
      const available = (await deps.listSkills?.(source)) ?? [];
      const matches = rankedSkills(available, query, [], Boolean(query));
      const start = Math.max(0, Math.floor(offset));
      const selected = matches.slice(start, start + Math.max(1, Math.min(100, Math.floor(limit))));
      const sourceScopeId = selected.length && source ? selected[0]!.skill!.scopeId : null;
      const end = start + selected.length;
      return {
        sourceScopeId,
        skills: selected.map(({ skill }) => ({
          id: skill!.id,
          name: skill!.manifest.name,
          description: skill!.manifest.description,
          source: skill!.scopeId,
        })),
        ...(end < matches.length ? { nextOffset: end } : {}),
      };
    },

    async skill(
      name: string,
      opts?: { path?: string; sandboxId?: string; source?: string; signal?: AbortSignal },
    ): Promise<SkillResult> {
      opts?.signal?.throwIfAborted();
      if (!deps.useSkill) return { content: null, sourceScopeId: null };
      if (opts?.sandboxId !== undefined && (!deps.sandboxResources || !deps.provisionResource))
        throw new Error("named sandboxes are not available here");
      return withAbort(
        () => deps.useSkill!(name, opts?.path ?? "SKILL.md", opts?.sandboxId, opts?.source),
        opts?.signal,
      );
    },

    async write(path: string, data: string, sandboxId?: string): Promise<void> {
      if (deps.memory && deps.memoryScopeId && isUnderAnyDir(path, ["memory"])) {
        throw new Error(
          `your durable memory isn't a file — use the \`memory\` tool instead (actions "add", "edit" and "delete")`,
        );
      }
      const { handle, resource, crossScope, durableRef } = await machine(sandboxId);
      if (crossScope) throw new Error("files write needs a computer owned by this conversation");
      const ownerScopeId = resource?.ownerScopeId ?? writableScopeId;
      const rel = path.startsWith("/") ? workspacePathOf(handle.rootDir, path) : path;
      if (rel === null)
        throw new Error(
          `${path} is not in the computer's workspace; only workspace files can be written, so name it relative to the workspace`,
        );
      await once(() =>
        timed("file_op", async () => {
          await deps.sandbox.writeFile(handle, rel, data);
          if (ownerScopeId && !isUnderAnyDir(rel, persistExclude))
            await deps.workspace.write(ownerScopeId, durableRef(rel), data);
        }),
      );
    },

    async publish(input: PublishInput): Promise<PublishResult> {
      if (!writableScopeId) throw new Error("publish needs a writable scope to own the app");
      if (input.share !== undefined || input.public !== undefined)
        throw new Error("publish does not accept sharing options; use apps action share to change access");
      const owner: ScopeId = scopeId("personal", deps.createdBy);
      const createdInScope: ScopeId = writableScopeId;
      let effectiveEntrypoint = input.entrypoint;
      if (effectiveEntrypoint === undefined && input.rollbackTo === undefined) {
        const shouldInheritForRename = input.renameFrom !== undefined && input.dir !== undefined;
        const priorName =
          input.renameFrom === undefined || shouldInheritForRename ? (input.renameFrom ?? input.name) : undefined;
        const prior = priorName ? await deps.deploy.getDeployment(priorName) : null;
        effectiveEntrypoint = deploymentEntrypoint(prior);
        if (!effectiveEntrypoint && input.renameFrom === undefined) {
          throw new Error('publish requires an entrypoint, e.g. "node server.js"');
        }
      }
      if (effectiveEntrypoint && input.dir && hasParentPathSegment(input.dir)) {
        throw new Error("publish directory must stay inside the workspace — no .. path segments");
      }
      if (!effectiveEntrypoint && input.sandboxId !== undefined) await accessSandbox(input.sandboxId);
      const files: DeployFile[] = effectiveEntrypoint
        ? filesUnder(await collectTree(deps.sandbox, (await machine(input.sandboxId)).handle, input.dir), input.dir)
        : [];
      if (effectiveEntrypoint && files.length === 0) {
        throw new Error(`publish: no files found under ${input.dir ?? "."} - nothing to deploy`);
      }
      const authEnv = effectiveEntrypoint
        ? Object.assign(
            {},
            ...(deps.layerAuth?.splitEnvTemplates ?? []).map((template) =>
              interpolateSplitEnv(template, { actingSlackUserId: deps.actingSlackUserId }),
            ),
          )
        : {};

      return once(async () => {
        const d = await deps.deploy.deployOrUpdate({
          ownerScopeId: owner,
          createdBy: deps.createdBy,
          createdInScope,
          files,
          ...(input.entrypoint ? { entrypoint: input.entrypoint } : {}),
          ...(input.name !== undefined ? { name: input.name } : {}),
          ...(input.renameFrom !== undefined ? { renameFrom: input.renameFrom } : {}),
          ...(input.env !== undefined ? { env: input.env } : {}),
          ...(Object.keys(authEnv).length ? { stampEnv: authEnv } : {}),
          ...(input.rollbackTo !== undefined ? { rollbackTo: input.rollbackTo } : {}),
          ...(input.alwaysOn !== undefined ? { alwaysOn: input.alwaysOn } : {}),
          ...(input.embedAncestors !== undefined ? { embedAncestors: input.embedAncestors } : {}),
        });
        const ref = d.name ?? d.id;
        const grantees = await deps.deploy.deploymentGrantees(d.id);
        const audience = audienceFromGrantees(
          grantees.map((g) => g.scope),
          d.createdInScope,
        );
        const urlBase = deps.publicWebUrl?.replace(/\/$/, "") ?? "";
        const url = publicUrlOf(d.endpoint) ?? `${urlBase}/d/${ref}/`;
        const dataDir = effectiveEntrypoint ? deps.deploy.providerProfile?.dataDir : undefined;
        return {
          id: d.id,
          ...(d.name ? { name: d.name } : {}),
          version: d.currentVersion,
          url,
          audience,
          ...(dataDir ? { dataDir } : {}),
          ...(d.alwaysOn ? { alwaysOn: true } : {}),
          ...(d.embedAncestors?.length ? { embedAncestors: d.embedAncestors } : {}),
          ...(d.public ? { public: true } : {}),
        };
      });
    },

    async setDeploymentPublic(id: string, isPublic: boolean) {
      const d = await deps.deploy.setDeploymentPublic(id, isPublic, { createdBy: deps.createdBy });
      return { id: d.id, ...(d.name ? { name: d.name } : {}), public: d.public === true };
    },

    async memorySearch(q: string, limit?: number, scope?: ScopeId): Promise<string[] | null> {
      if (deps.context) return timed("recall", () => deps.context!.searchMemory(q, limit, scope));
      if (!memory) return null;
      return timed("recall", () =>
        searchNotebooks(memory!, deps.memoryAccess?.read ?? [], q, limit, scope, deps.createdBy),
      );
    },

    async memoryRead(scope?: ScopeId): Promise<string | null> {
      const target = scope ?? deps.memoryAccess?.write ?? deps.memoryScopeId;
      if (!memory || !target || !canReadNotebook(deps.memoryAccess ?? { read: [] }, target)) return null;
      const body = await timed("recall", async () => {
        if (deps.context && deps.memoryAccess?.read.includes(target)) return deps.context.readMemory(target);
        return readNotebook(memory!, target);
      });
      if (body === null) return null;
      return scope !== undefined ? `### ${target}\n${body}` : body;
    },

    async memoryAdd(facts: string[]): Promise<number | null> {
      const write = deps.memoryAccess?.write;
      if (!memory || !write) return null;
      return once(() =>
        timed("memory_write", () =>
          memory!.capture(write, facts, Date.now(), deps.createdBy, {
            ...deps.memoryCaptureMetadata?.(),
            mode: "explicit",
            actorId: deps.createdBy,
            conversationScopeId: writableScopeId ?? write,
          }),
        ),
      );
    },

    async memoryEdit(edits: MemoryEdit[]): Promise<true | null> {
      const write = deps.memoryAccess?.write;
      if (!memory?.edit || !write) return null;
      return once(() =>
        timed("memory_write", async () => {
          await memory!.edit!(write, edits, deps.createdBy, {
            ...deps.memoryCaptureMetadata?.(),
            conversationScopeId: writableScopeId ?? write,
          });
          return true as const;
        }),
      );
    },

    async memoryDelete(ids: string[]): Promise<true | null> {
      const write = deps.memoryAccess?.write;
      if (!memory?.delete || !write) return null;
      return once(() =>
        timed("memory_write", async () => {
          await memory!.delete!(write, ids, deps.createdBy);
          return true as const;
        }),
      );
    },

    ...(deps.humanTurn ? { humanTurn: true } : {}),
    ...(deps.sessionSyscalls ? { sessionSyscalls: deps.sessionSyscalls } : {}),

    async history(q: string, limit?: number): Promise<string[]> {
      if (!deps.sessionHistory) return [];
      return deps.sessionHistory.search(q, limit);
    },

    async historyOpen(seq: number): Promise<string | null> {
      if (!deps.sessionHistory) return null;
      return deps.sessionHistory.open(seq);
    },

    async callMcpTool(name: string, args: Record<string, unknown>, approval?: string): Promise<string> {
      if (!deps.mcp) throw new Error("no MCP connectors are configured");
      return deps.mcp.call(name, args, deps.createdBy, approval);
    },

    async mcpToolNeedsApproval(name: string, args: Record<string, unknown>): Promise<boolean> {
      if (!deps.mcp) throw new Error("no MCP connectors are configured");
      return deps.mcp.needsApproval(name, args, deps.createdBy);
    },

    async awaitClientResult(callId, timeoutMs, signal, toolName) {
      if (toolName === "desktop" && !deps.desktopClientId)
        return { content: "Computer access unavailable; continue from QM desktop.", isError: true };
      if (!deps.signals || runId === undefined) throw new Error("client tools need a queued run");
      return waitForClientResult(deps.signals, runId, callId, { timeoutMs, ...(signal ? { signal } : {}) });
    },

    async backgroundStart(
      command: string,
      opts: { purpose: string; ttlSeconds?: number; sandboxId?: string; credentials?: string[] },
    ): Promise<BackgroundStartResult> {
      if (!deps.backgroundBroker) throw new Error(BACKGROUND_UNAVAILABLE_MESSAGE);
      const requestedCredentials = opts.credentials ?? [];
      if (requestedCredentials.length && !writableScopeId)
        throw new Error("command credentials are available only on scoped computers");
      const requested = await selectCredentials(requestedCredentials, false);
      const policy = deps.commandPolicy;
      let handle: SandboxHandle;
      if (opts?.sandboxId !== undefined) {
        if (!deps.sandboxResources || !deps.provisionResource) throw new Error("sandbox inventory unavailable");
        const access = await accessSandbox(opts.sandboxId);
        handle = await deps.provisionResource(access, (current) => {
          if (current.crossScope && requestedCredentials.length)
            throw new Error("command credentials cannot be copied to another scope's computer");
          authorizeExecution(command, current, policy());
        });
      } else {
        authorizeExecution(command, undefined, policy());
        handle = await deps.provision();
      }
      return once(
        async () => {
          const staged = requested.length ? await stageCredentials(requested, handle, "background") : undefined;
          const release = async () => {
            await staged?.fileExecution?.finish();
          };
          let credentials: BackgroundCredentials | undefined;
          try {
            credentials = staged && {
              env: staged.commandEnv,
              secrets: Object.values(executionSecretEnv(staged.commandEnv, staged.secretValues)),
              ...(staged.fileExecution
                ? { files: processCredentialFiles(staged.fileExecution.plan, staged.fileCredentials) }
                : {}),
              release,
            };
          } catch (error) {
            return withCleanup(() => Promise.reject(error), release);
          }
          return deps.backgroundBroker!.start(
            handle,
            command,
            opts.purpose,
            opts?.ttlSeconds ? opts.ttlSeconds * 1000 : undefined,
            credentials,
          );
        },
        () => true,
      );
    },

    async backgroundPoll(
      processId: string,
      opts?: { sinceCursor?: number; maxBytes?: number; waitSeconds?: number },
    ): Promise<BackgroundPollResult> {
      if (!deps.backgroundBroker) throw new Error(BACKGROUND_UNAVAILABLE_MESSAGE);
      const handle = (await deps.backgroundBroker.handleFor?.(processId)) ?? (await deps.provision());
      return once(
        () =>
          deps.backgroundBroker!.poll(handle, processId, {
            ...(opts?.sinceCursor !== undefined ? { sinceCursor: opts.sinceCursor } : {}),
            ...(opts?.maxBytes !== undefined ? { maxBytes: opts.maxBytes } : {}),
            ...(opts?.waitSeconds !== undefined ? { waitMs: opts.waitSeconds * 1000 } : {}),
          }),
        (r) => r.status.state === "exited",
      );
    },

    async backgroundStop(processId: string, signal?: string): Promise<BackgroundStopResult> {
      if (!deps.backgroundBroker) throw new Error(BACKGROUND_UNAVAILABLE_MESSAGE);
      const handle = (await deps.backgroundBroker.handleFor?.(processId)) ?? (await deps.provision());
      return once(
        () => deps.backgroundBroker!.stop(handle, processId, signal),
        () => true,
      );
    },

    async backgroundWrite(processId: string, data: string): Promise<BackgroundWriteResult> {
      if (!deps.backgroundBroker) throw new Error(BACKGROUND_UNAVAILABLE_MESSAGE);
      const handle = (await deps.backgroundBroker.handleFor?.(processId)) ?? (await deps.provision());
      return once(
        () => deps.backgroundBroker!.write(handle, processId, data),
        () => true,
      );
    },

    async backgroundList(): Promise<BackgroundJobSummary[]> {
      if (!deps.backgroundBroker) return [];
      return deps.backgroundBroker.list();
    },

    async backgroundWatch(processId, opts) {
      if (!deps.monitorBroker) throw new Error(WATCH_UNAVAILABLE_MESSAGE);
      return once(
        () => deps.monitorBroker!.watch(processId, opts),
        () => true,
      );
    },

    async backgroundUnwatch(monitorId) {
      if (!deps.monitorBroker) throw new Error(WATCH_UNAVAILABLE_MESSAGE);
      return once(
        () => deps.monitorBroker!.unwatch(monitorId),
        () => true,
      );
    },

    cronCreate: (req) =>
      controlOp(
        (c, cl) => c.createCron(req, cl),
        (r) => r.ok,
      ),
    cronList: () => controlOp((c, cl) => c.listCrons(cl)),
    cronGet: (id) => controlOp((c, cl) => c.getCron(id, cl)),
    cronRuns: (id, req) => controlOp((c, cl) => c.getCronRuns(id, req ?? {}, cl)),
    cronPatch: (id, req) =>
      controlOp(
        (c, cl) => c.patchCron(id, req, cl),
        (r) => r.ok,
      ),
    cronNote: (id, note) =>
      controlOp(
        (c, cl) => c.noteCron(id, note, cl),
        (r) => r.ok,
      ),
    cronDelete: (id) =>
      controlOp(
        (c, cl) => c.deleteCron(id, cl),
        (r) => r.ok,
      ),
    cronSetEnabled: (id, enabled) =>
      controlOp(
        (c, cl) => c.setCronEnabled(id, enabled, cl),
        (r) => r.ok,
      ),
    cronRun: (id) =>
      controlOp(
        (c, cl) => c.runCron(id, cl),
        (r) => r.ok,
      ),
    cronRetarget: (id, destinationKey) =>
      controlOp(
        (c, cl) => c.retargetCron(id, destinationKey, cl),
        (r) => r.ok,
      ),
    webhookCreate: (req) =>
      controlOp(
        (c, cl) => c.createWebhook(req, cl, deps.webhookPublicUrl),
        (r) => r.ok,
      ),
    webhookList: () => controlOp((c, cl) => c.listWebhooks(cl)),
    webhookDisable: (id) =>
      controlOp(
        (c, cl) => c.disableWebhook(id, cl),
        (r) => r.ok,
      ),
    webhookUpdate: (id, action) =>
      controlOp(
        (c, cl) => c.updateWebhook(id, { action }, cl),
        (r) => r.ok,
      ),
    soulRead() {
      if (!deps.control || !deps.controlClaims) return CONTROL_UNAVAILABLE;
      return deps.control.readSoul(deps.controlClaims);
    },
    soulWrite: (content, expectedVersion) =>
      controlOp(
        async (c, cl) => c.writeSoul(content, cl, expectedVersion),
        (r) => r.ok,
      ),
    shareArtifact: (req) =>
      controlOp(
        (c, cl) => c.shareArtifact(req, cl),
        (r) => r.ok,
      ),

    post: (text, opts, files, sandboxId) =>
      surfaceOp(
        (s) => s.post(text, opts, files, sandboxId),
        (r) => r.ok,
      ),
    reach: (text, target, files, sandboxId) =>
      surfaceOp(
        (s) => s.reach(text, target, files, sandboxId),
        (r) => r.ok,
      ),
    react: (input) =>
      surfaceOp(
        (s) => s.react(input),
        (r) => r.ok,
      ),
    edit: (input) =>
      surfaceOp(
        (s) => s.edit(input),
        (r) => r.ok,
      ),
    delete: (input) =>
      surfaceOp(
        (s) => s.delete(input),
        (r) => r.ok,
      ),
    readThread: (opts) => surfaceOp((s) => s.readThread(opts)),
    whatsNew: (opts) => surfaceOp((s) => s.whatsNew(opts)),
    search: (query, opts) => surfaceOp((s) => s.search(query, opts)),
    readMembers: () => surfaceOp((s) => s.readMembers()),
    readFile: (ref) => surfaceOp((s) => s.readFile(ref)),
    getStandingOrder: () => surfaceOp((s) => s.getStandingOrder()),
    setStandingOrder: (orders, bots, ambientEnabled, expectedOrders) =>
      surfaceOp((s) => s.setStandingOrder(orders, bots, ambientEnabled, expectedOrders)),
    attach: (files, sandboxId) =>
      deps.attach
        ? deps.attach(files, sandboxId)
        : Promise.resolve({ ok: false as const, message: ATTACH_UNAVAILABLE_MESSAGE }),
  };
}

const ATTACH_UNAVAILABLE_MESSAGE =
  "files can't be attached from this turn — name the file in the surface `post` action's `files` instead";

const SURFACE_UNAVAILABLE_MESSAGE =
  "the chat surface isn't reachable from this turn — there's no conversation to post to or read here";

const BACKGROUND_UNAVAILABLE_MESSAGE =
  "Background execution isn't available on this computer — run the command with `execute` (up to 300s) instead.";
const WATCH_UNAVAILABLE_MESSAGE =
  "Watching background jobs isn't available on this computer — `background poll` the job from a later turn instead.";

function audienceFromGrantees(
  granteeScopeIds: readonly ScopeId[],
  createdInScope?: ScopeId,
): PublishAudienceDescriptor {
  if (granteeScopeIds.length === 0) return { kind: "owner" };
  const orgGrant = granteeScopeIds.find((g) => parseScopeId(g).kind === "org");
  if (orgGrant) return { kind: "org", orgId: parseScopeId(orgGrant).ref };
  const origin = createdInScope ? parseScopeId(createdInScope) : { kind: null, ref: "" };
  return {
    kind: "members",
    ...(origin.kind === "channel" ? { channelRef: origin.ref } : {}),
    ...(granteeScopeIds.every((g) => parseScopeId(g).kind === "personal")
      ? { memberCount: granteeScopeIds.length }
      : {}),
  };
}

function tryDecodeUtf8(bytes: Uint8Array): string | null {
  try {
    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
  } catch {
    return null;
  }
}

const COMMAND_PATH_PROBE_TIMEOUT_MS = 10_000;

async function collectTree(
  sandbox: Sandbox,
  handle: SandboxHandle,
  dir?: string,
): Promise<Array<{ path: string; data: Uint8Array }>> {
  const base = (dir ?? "").replace(/^\.?\/+/, "").replace(/\/+$/, "");
  if (supportsAgentComputerExport(sandbox)) {
    try {
      const entries = await sandbox.exportFiles(handle, {
        include: ["workspace"],
        ...(base && base !== "." ? { includePaths: [base] } : {}),
        exclude: (entry) => carriesGitMetadata(entry.path),
        keepContentCaches: true,
      });
      return entries.filter((e) => !carriesGitMetadata(e.path)).map((e) => ({ path: e.path, data: e.data }));
    } catch (e) {
      if (!(e instanceof CapabilityUnsupportedError)) throw e;
      console.warn(`[publish] ${e.message}; falling back to per-file reads`);
    }
  }
  const out: Array<{ path: string; data: Uint8Array }> = [];
  for (const path of await sandbox.listDir(handle, base || ".")) {
    if (carriesGitMetadata(path)) continue;
    const data = await sandbox.readFileBytes(handle, path);
    if (data === null) throw new Error(`publish: could not read ${path} from the app tree`);
    out.push({ path, data });
  }
  return out;
}

function isUnderAnyDir(path: string, dirs: readonly string[]): boolean {
  const p = path.replace(/^\.?\/+/, "").replace(/\/+$/, "");
  return dirs.some((raw) => {
    const dir = raw.replace(/^\.?\/+/, "").replace(/\/+$/, "");
    return dir !== "" && (p === dir || p.startsWith(`${dir}/`));
  });
}

function filesUnder(snapshot: Array<{ path: string; data: Uint8Array }>, dir?: string): DeployFile[] {
  const d = (dir ?? "").replace(/^\.?\/+/, "").replace(/\/+$/, "");
  if (!d || d === ".") return snapshot.map((f) => ({ path: f.path, data: f.data }));
  const prefix = `${d}/`;
  return snapshot
    .filter((f) => f.path.startsWith(prefix))
    .map((f) => ({ path: f.path.slice(prefix.length), data: f.data }));
}