@oharness/engine 0.9.2 → 0.10.0

package/dist/tools/types.d.ts

@@ -42,7 +42,91 @@ export interface SubagentRunOptions {
     description?: string;
     model?: string;
     signal?: AbortSignal;
+    /**
+     * `worktree`: run in a fresh worktree beside the project, so its edits
+     * cannot collide with the parent's. Kept afterwards only if it changed
+     * something.
+     */
+    isolation?: "worktree";
+    /**
+     * Hand the subagent the computer_* tools. Only honoured where the parent
+     * conversation has Computer Use switched on; never inherited otherwise.
+     */
+    computer?: boolean;
+}
+export type BackgroundTaskStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
+/** One background task as tools and frontends see it. */
+export interface BackgroundTaskView {
+    id: string;
+    agentType: string;
+    description: string;
+    status: BackgroundTaskStatus;
+    queuedAt: number;
+    startedAt?: number;
+    endedAt?: number;
+    turns: number;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    /** What it is doing right now, while it runs: the title of its current tool. */
+    activity?: string;
+    /** Its final message, once it has completed. */
+    result?: string;
+    error?: string;
+    /** Where its edits were kept, when it ran in a worktree and changed something. */
+    worktree?: string;
+    /**
+     * Put away by the person: an ended task they no longer want listed over the
+     * composer. Still there to open and follow up; a follow-up brings it back.
+     */
+    dismissed?: boolean;
+}
+/**
+ * Subagents that run on while the conversation goes on, their results read
+ * back in when they end. Lent only where something can deliver a result that
+ * arrives after the turn that asked for it has finished.
+ */
+export interface BackgroundTaskHost {
+    start(opts: SubagentRunOptions): BackgroundTaskView;
+    get(id: string): BackgroundTaskView | undefined;
+    list(): BackgroundTaskView[];
+    stop(id: string): boolean;
+    /**
+     * Message a task: read at its next gap while it runs; for one that has
+     * ended, a new run that continues its conversation. Stopped tasks refuse.
+     */
+    send(id: string, message: string): "interjected" | "resumed" | "unknown" | "stopped" | "busy";
+    /** Put an ended task away from the list over the composer. */
+    dismiss(id: string): boolean;
+}
+export interface WorktreeStartOptions {
+    /** What the new session is for; also what the worktree is named after. */
+    task: string;
+    /** ASCII name for the directory and branch when the task has none. */
+    slug?: string;
+    type?: "feat" | "fix" | "chore" | "docs";
+    /** The first message of the new session. */
+    prompt: string;
 }
+export interface WorktreeStartResult {
+    sessionId: string;
+    path: string;
+    kind: "git" | "clone";
+    branch?: string;
+}
+/**
+ * What a frontend lends the engine to host a worktree session: given the
+ * session asking and what it asked for, make the worktree and start the
+ * session there. The engine cannot do this itself — sessions belong to
+ * whichever frontend holds them.
+ */
+export type WorktreeLauncher = (request: WorktreeStartOptions & {
+    from: {
+        cwd: string;
+        sessionId: string;
+    };
+}) => Promise<WorktreeStartResult>;
 export interface SubagentRunResult {
     text: string;
     turns: number;
@@ -57,7 +141,15 @@ export interface ToolHost {
     listSubagentTypes(): Array<{
         name: string;
         description: string;
+        readOnly?: boolean;
+        isolation?: "worktree";
     }>;
+    /**
+     * Subagents that run in the background. Absent where a result that arrives
+     * after the turn has ended would reach nobody — headless runs, subagents —
+     * and the task tool then runs the work in the foreground instead.
+     */
+    backgroundTasks?: BackgroundTaskHost;
     /** Shared, session-scoped scratch state (the todo list lives here). */
     state: Map<string, unknown>;
     /**
@@ -70,6 +162,12 @@ export interface ToolHost {
      * layer still never imports the agent.
      */
     resolvePath?(input: string, access: "read" | "write"): string;
+    /**
+     * Make a worktree beside the project and start a new session in it with a
+     * prompt, returning at once. Absent where no frontend can host a second
+     * session (headless, the terminal UI, subagents).
+     */
+    startWorktree?(opts: WorktreeStartOptions): Promise<WorktreeStartResult>;
 }
 export interface Tool {
     name: string;
@@ -81,8 +179,22 @@ export interface Tool {
      * Anything that mutates state or reaches the network should leave this off.
      */
     readOnly?: boolean;
+    /**
+     * Changes nothing, so plan mode lets it run — but unlike `readOnly` it still
+     * goes through the permission prompt. For tools whose reading is itself the
+     * thing to approve: a screenshot of another app shows whatever is in it.
+     */
+    observes?: boolean;
     /** Safe to run concurrently with other tools in the same assistant turn. */
     concurrencySafe?: boolean;
+    /**
+     * The same question asked of one call, for a tool whose answer depends on
+     * its input. Consulted only when `concurrencySafe` is not already true; it
+     * receives the raw, unvalidated input, so it must tolerate anything. The
+     * host says what the call would actually do here — a background task
+     * where none can be offered runs in the foreground, for instance.
+     */
+    concurrencySafeFor?(input: unknown, host: ToolHost): boolean;
     /**
      * Mutates only this session's own scratch state — no file, no command, no
      * network, nothing that outlives the process.

package/dist/tools/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AA8HA,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,QAAkC;IACvE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAClF,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,QAAgB,EAAE,IAAY,EAAE,OAAgB;IACxE,MAAM,OAAO,GAAgB,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IACjE,IAAI,OAAO;QAAE,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IAC9D,OAAO,EAAE,OAAO,EAAE,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAkB;IAC/C,OAAO,MAAM,CAAC,OAAO;SAClB,MAAM,CAAC,CAAC,CAAC,EAAkB,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC;SAChD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;SAClB,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AA4OA,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,QAAkC;IACvE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAClF,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,QAAgB,EAAE,IAAY,EAAE,OAAgB;IACxE,MAAM,OAAO,GAAgB,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IACjE,IAAI,OAAO;QAAE,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IAC9D,OAAO,EAAE,OAAO,EAAE,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAkB;IAC/C,OAAO,MAAM,CAAC,OAAO;SAClB,MAAM,CAAC,CAAC,CAAC,EAAkB,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC;SAChD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;SAClB,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC"}

package/dist/worktree/index.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Worktrees: a sibling copy of a project for a task that runs beside another.
+ *
+ * Two sessions in one checkout edit the same files. A worktree gives the
+ * second one its own tree next to the first — `OHarness/` and
+ * `OHarness-fix-tmp-writes/` — so neither sees the other's half-made edits.
+ *
+ * A git repository gets a real `git worktree` on a branch of its own, based on
+ * the remote's default branch. A plain directory gets a copy-on-write clone,
+ * and its changes are tracked by a **shadow repository** kept under the user
+ * directory: nothing is written into the folder that would not have been
+ * there anyway, and "apply back" is a diff against the moment it was made.
+ *
+ * Every worktree made here is recorded in `worktrees.json`, so the app can
+ * show it under the project it came from and offer the way out of it.
+ */
+export type WorktreeKind = "git" | "clone";
+export type BranchType = "feat" | "fix" | "chore" | "docs";
+export declare const BRANCH_TYPES: readonly BranchType[];
+export interface Worktree {
+    id: string;
+    kind: WorktreeKind;
+    /** The worktree's own root. */
+    path: string;
+    /**
+     * Where sessions in it run. The root, unless the project was a folder
+     * inside a larger repository — then the same folder inside the worktree.
+     */
+    cwd: string;
+    /** The project directory it was made from. */
+    source: string;
+    /** git: the main worktree of the repository. */
+    repo?: string;
+    /** git: the branch created for it. */
+    branch?: string;
+    /** git: what the branch started from, by name (`origin/main`, `HEAD`). */
+    baseRef?: string;
+    /** The commit it started from: the base commit, or the shadow's baseline. */
+    base?: string;
+    /** clone: the shadow repository tracking it. */
+    shadow?: string;
+    task: string;
+    slug: string;
+    type: BranchType;
+    createdAt: number;
+}
+export interface WorktreeStatus {
+    exists: boolean;
+    /** Changed paths, as `git status --porcelain` lists them. */
+    changes: string[];
+    /** git: commits on the branch since it started. */
+    commits: number;
+    /** Whether finishing it loses nothing: no changes and no commits. */
+    clean: boolean;
+}
+export type FinishAction = "remove" | "discard" | "commit" | "push" | "merge" | "apply";
+export interface FinishResult {
+    action: FinishAction;
+    /** Whether the worktree is gone afterwards. */
+    removed: boolean;
+    message: string;
+    /** push: where to open a pull request, when the remote is known. */
+    url?: string;
+}
+export interface CreateOptions {
+    task: string;
+    /** The name's tail. Derived from the task when it is left out. */
+    slug?: string;
+    type?: BranchType;
+    /** git: start from this instead of the remote's default branch. */
+    base?: string;
+    /** Skip `git fetch` (tests, offline). */
+    fetch?: boolean;
+}
+/**
+ * A directory- and branch-safe name from free text: lowercase ASCII words
+ * joined by hyphens, at most 40 characters, cut at a word boundary.
+ *
+ * Returns "" when nothing ASCII is left — a title written in Chinese, say —
+ * so the caller can ask for a slug instead of inventing a meaningless one.
+ */
+export declare function slugify(text: string): string;
+/** The branch type a task reads as. `feat` unless it says otherwise. */
+export declare function branchType(task: string): BranchType;
+export declare function listWorktrees(): Promise<Worktree[]>;
+/** The worktree a directory belongs to: its root, its session cwd, or anything inside. */
+export declare function findWorktree(dir: string): Promise<Worktree | undefined>;
+/**
+ * The name a worktree for this task would get, without making it — what a
+ * dialog shows before the person confirms.
+ */
+export declare function previewWorktree(projectDir: string, opts: {
+    task: string;
+    slug?: string;
+    type?: BranchType;
+}): Promise<{
+    kind: WorktreeKind;
+    path: string;
+    branch?: string;
+    slug: string;
+    type: BranchType;
+}>;
+export declare function createWorktree(projectDir: string, opts: CreateOptions): Promise<Worktree>;
+export declare function worktreeStatus(one: Worktree): Promise<WorktreeStatus>;
+/** `git@github.com:a/b.git` or `https://github.com/a/b(.git)` → `https://github.com/a/b`. */
+export declare function webUrl(remote: string): string | undefined;
+export declare function finishWorktree(one: Worktree, action: FinishAction, opts?: {
+    message?: string;
+}): Promise<FinishResult>;