@oharness/engine 0.9.3 → 0.11.0

package/dist/acp/runner.d.ts

@@ -0,0 +1,80 @@
+import type { PermissionAnswer } from "../agent/permissions.ts";
+import type { AcpFileSystem, AcpMcpServer, AcpStopReason, AcpUpdate } from "./client.ts";
+/**
+ * A subagent whose loop is someone else's: an external agent reached over ACP.
+ *
+ * Declared on a subagent definition. The harness keeps everything around the
+ * run — the `task` tool, background tasks, worktrees, permission cards — and
+ * hands the turn itself to the agent named here.
+ */
+export interface AcpRuntime {
+    kind: "acp";
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    /**
+     * What to tell the person when the agent says it needs signing in. The
+     * agent's own login is the only one offered: this is the sentence that
+     * sends them to it.
+     */
+    signInHint?: string;
+    /**
+     * Why this agent cannot run here — Node too old, say. Set at detection, so
+     * a task gets this sentence as its answer instead of a process that dies.
+     */
+    unavailable?: string;
+}
+/** The agent cannot run on this machine; the message says why. */
+export declare class AcpUnavailable extends Error {
+    constructor(message: string);
+}
+export declare function looksLikeSignIn(text: string): boolean;
+/** The agent refused to start a session until it is signed in. */
+export declare class AcpSignInRequired extends Error {
+    constructor(message: string);
+}
+export interface AcpRunOptions {
+    runtime: AcpRuntime;
+    cwd: string;
+    /** The prompt for a fresh session — a follow-up's carries what came before. */
+    prompt: string;
+    /**
+     * An earlier session of this task to pick up, and the prompt to send when
+     * it is picked up (the new message alone: the agent has the rest). Falls
+     * back to a fresh session and `prompt` when the agent cannot load it.
+     */
+    resume?: {
+        sessionId: string;
+        prompt: string;
+    };
+    /** MCP servers to give the agent, so it has this conversation's tools. */
+    mcpServers?: AcpMcpServer[];
+    /** Route the agent's file reads and writes through the workspace policy. */
+    fs?: AcpFileSystem;
+    signal?: AbortSignal;
+    /** Put one of the agent's tool calls to the person. */
+    askPermission(title: string, input: unknown, toolCallId: string): Promise<boolean | PermissionAnswer>;
+    /** What the agent is doing now, for a background task's status line. */
+    onActivity?(title: string): void;
+    /** Every update as it arrives, for a caller that shows the turn live. */
+    onUpdate?(update: AcpUpdate): void;
+}
+export interface AcpRunResult {
+    /** The agent's last say: what it wrote after its final tool call. */
+    text: string;
+    stopReason: AcpStopReason;
+    toolCalls: number;
+    /** The session this turn ran in, for the next follow-up to resume. */
+    sessionId: string;
+    /** Whether it continued an earlier session rather than starting one. */
+    resumed: boolean;
+}
+/**
+ * One turn of an external agent, start to finish: a process, a session, the
+ * prompt, and the process gone again.
+ *
+ * A process per turn rather than one kept warm: a task's follow-up may come
+ * after a restart, and the same path serving both is what keeps them alike.
+ * The conversation so far rides in the prompt instead.
+ */
+export declare function runAcpTurn(opts: AcpRunOptions): Promise<AcpRunResult>;

package/dist/acp/runner.js

@@ -0,0 +1,159 @@
+import { AcpClient, AcpError, ACP_AUTH_REQUIRED, allowOnce, refuse } from "./client.js";
+/** The agent cannot run on this machine; the message says why. */
+export class AcpUnavailable extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AcpUnavailable";
+    }
+}
+/**
+ * Replies that mean "not signed in" whatever form they arrive in.
+ *
+ * ACP has an error code for it, and an agent may use it — or may start the
+ * session anyway and answer the first prompt with its own login complaint,
+ * as text or as an error. All of them become the same sentence pointing at
+ * the agent's own login, so what the person reads does not depend on which
+ * an adapter version happened to do.
+ */
+const SIGN_IN_TEXT = /please run \/login|run `?claude`? (?:to )?(?:log|sign) ?in|invalid api key|not (?:logged|signed) in|authentication[_ ](?:error|required|failed)|oauth token (?:has )?expired/i;
+export function looksLikeSignIn(text) {
+    return SIGN_IN_TEXT.test(text);
+}
+/** The agent refused to start a session until it is signed in. */
+export class AcpSignInRequired extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AcpSignInRequired";
+    }
+}
+/**
+ * One turn of an external agent, start to finish: a process, a session, the
+ * prompt, and the process gone again.
+ *
+ * A process per turn rather than one kept warm: a task's follow-up may come
+ * after a restart, and the same path serving both is what keeps them alike.
+ * The conversation so far rides in the prompt instead.
+ */
+export async function runAcpTurn(opts) {
+    if (opts.runtime.unavailable)
+        throw new AcpUnavailable(opts.runtime.unavailable);
+    const signIn = () => new AcpSignInRequired(opts.runtime.signInHint ?? "The agent needs signing in. Run it in a terminal, sign in there, then try again.");
+    // Said before anything else: the first run fetches the adapter, which can
+    // take half a minute with nothing else to show for it.
+    opts.onActivity?.("Starting the agent…");
+    const client = new AcpClient({
+        command: opts.runtime.command,
+        ...(opts.runtime.args ? { args: opts.runtime.args } : {}),
+        ...(opts.runtime.env ? { env: opts.runtime.env } : {}),
+        cwd: opts.cwd,
+        ...(opts.fs ? { fs: opts.fs } : {}),
+    });
+    // A stop is first a `session/cancel`, which lets the agent end its turn
+    // tidily; an agent that has not ended it a few seconds later is closed.
+    const kill = () => setTimeout(() => client.close(), 3_000).unref?.();
+    opts.signal?.addEventListener("abort", kill, { once: true });
+    try {
+        await client.initialize();
+        const servers = opts.mcpServers ?? [];
+        let sessionId;
+        let prompt = opts.prompt;
+        let resumed = false;
+        try {
+            if (opts.resume && client.capabilities.loadSession) {
+                try {
+                    await client.loadSession(opts.resume.sessionId, opts.cwd, servers);
+                    sessionId = opts.resume.sessionId;
+                    prompt = opts.resume.prompt;
+                    resumed = true;
+                }
+                catch (err) {
+                    // Gone from the agent's side — cleared, or another machine's. A
+                    // fresh session with the history in its prompt is the fallback.
+                    if (err instanceof AcpError && err.code === ACP_AUTH_REQUIRED)
+                        throw err;
+                }
+            }
+            sessionId ??= await client.newSession(opts.cwd, servers);
+        }
+        catch (err) {
+            if (err instanceof AcpError && (err.code === ACP_AUTH_REQUIRED || looksLikeSignIn(err.message)))
+                throw signIn();
+            throw err;
+        }
+        // Text arrives in chunks between tool calls. What the parent wants is the
+        // agent's conclusion, so each tool call starts a fresh segment and the
+        // last one with anything in it is the answer.
+        const segments = [""];
+        const titles = new Map();
+        let toolCalls = 0;
+        let stopReason;
+        try {
+            stopReason = await client.prompt(sessionId, prompt, {
+                onUpdate(update) {
+                    opts.onUpdate?.(update);
+                    switch (update.sessionUpdate) {
+                        case "agent_message_chunk": {
+                            const content = update.content;
+                            if (content?.type === "text" && content.text)
+                                segments[segments.length - 1] += content.text;
+                            break;
+                        }
+                        case "tool_call": {
+                            const call = update;
+                            toolCalls++;
+                            const title = call.title || call.kind || "tool";
+                            titles.set(call.toolCallId, title);
+                            opts.onActivity?.(title);
+                            if (segments[segments.length - 1].trim())
+                                segments.push("");
+                            break;
+                        }
+                        case "tool_call_update": {
+                            const call = update;
+                            if (call.title)
+                                titles.set(call.toolCallId, call.title);
+                            break;
+                        }
+                        case "plan": {
+                            const entries = update.entries ?? [];
+                            const current = entries.find((entry) => entry.status === "in_progress") ?? entries[0];
+                            if (current)
+                                opts.onActivity?.(current.content);
+                            break;
+                        }
+                    }
+                },
+                async onPermission(request) {
+                    const title = request.toolCall.title || titles.get(request.toolCall.toolCallId) || "a tool call";
+                    const answer = await opts.askPermission(title, request.toolCall.rawInput, request.toolCall.toolCallId);
+                    const allowed = typeof answer === "boolean" ? answer : answer.allow;
+                    if (!allowed)
+                        return refuse(request.options);
+                    // "Always" is the person's to give, and only when they gave it: it
+                    // is remembered on the agent's side, beyond this card.
+                    const always = typeof answer === "object" && answer.remember
+                        ? request.options.find((option) => option.kind === "allow_always")
+                        : undefined;
+                    return always ? { outcome: "selected", optionId: always.optionId } : allowOnce(request.options);
+                },
+            }, opts.signal);
+        }
+        catch (err) {
+            // A login complaint can also come back as the prompt's error.
+            if (err instanceof AcpError && (err.code === ACP_AUTH_REQUIRED || looksLikeSignIn(err.message)))
+                throw signIn();
+            throw err;
+        }
+        const text = [...segments].reverse().find((segment) => segment.trim())?.trim() ?? "";
+        // Or as the whole of its answer, before it ever got to a tool: a short
+        // reply that is only a login complaint is the sign-in, not a result.
+        if (toolCalls === 0 && text.length < 400 && looksLikeSignIn(text))
+            throw signIn();
+        return { text, stopReason, toolCalls, sessionId, resumed };
+    }
+    finally {
+        opts.signal?.removeEventListener("abort", kill);
+        client.close();
+    }
+}
+//# sourceMappingURL=runner.js.map

package/dist/acp/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/acp/runner.ts"],"names":[],"mappings":"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"}

package/dist/agent/agent.d.ts

@@ -1,9 +1,10 @@
+import type { SessionGoal } from "./goal.ts";
 import type { RuntimeAuditEvent } from "../core/audit.ts";
 import type { Message, StopReason, Usage } from "../core/types.ts";
 import type { McpManager } from "../mcp/manager.ts";
 import type { ThinkingConfig } from "../providers/types.ts";
 import type { ToolFilter, ToolRegistry } from "../tools/registry.ts";
-import type { SubagentRunOptions, SubagentRunResult, ToolHost, ToolProgress, ToolResult } from "../tools/types.ts";
+import type { BackgroundTaskHost, BackgroundTaskView, SubagentRunOptions, SubagentRunResult, ToolHost, ToolProgress, ToolResult, WorktreeLauncher, WorktreeStartOptions, WorktreeStartResult } from "../tools/types.ts";
 import type { ArtifactDescriptor } from "../artifacts/store.ts";
 import type { Logger } from "../util/logger.ts";
 import type { WorkspacePolicy } from "./workspace.ts";
@@ -12,7 +13,8 @@ import { MemoryStore } from "./memory.ts";
 import type { ExtractedSummary, MemoryProvider, MemoryRecallItem } from "./memory-provider.ts";
 import type { CompactionOptions } from "./compaction.ts";
 import { HookRegistry } from "./hooks.ts";
-import type { PermissionPrompt, PermissionRequest } from "./permissions.ts";
+import type { AcpFileSystem } from "../acp/client.ts";
+import type { PermissionAnswer, PermissionPrompt, PermissionRequest } from "./permissions.ts";
 import type { QuestionPrompt, QuestionRequest, QuestionResult } from "../tools/questions.ts";
 import type { Session } from "./session.ts";
 import { SubagentRegistry } from "./subagent.ts";
@@ -89,6 +91,8 @@ export type AgentEvent = {
     reason?: string;
     /** Pattern written to settings, when the approval was persisted. */
     remembered?: string;
+    /** Held back by plan mode: the mode doing its job, not a refusal. */
+    plan?: boolean;
 }
 /**
  * Something the user said while the turn was already running has just been
@@ -99,6 +103,15 @@ export type AgentEvent = {
     type: "interjected";
     id: string;
     text: string;
+}
+/**
+ * Background tasks have ended and their results were just read into the
+ * conversation, as `text`. Emitted where they enter, like an interjection.
+ */
+ | {
+    type: "task_notification";
+    tasks: BackgroundTaskView[];
+    text: string;
 } | {
     type: "compacted";
     tokensBefore: number;
@@ -130,6 +143,11 @@ export type AgentEvent = {
     type: "notice";
     message: string;
 }
+/** The session's goal was set, nudged, achieved or reported blocked. */
+ | {
+    type: "goal";
+    goal: SessionGoal;
+}
 /**
  * `status` is the HTTP status behind a provider failure, when one could be
  * recovered. It travels beside the message because some statuses are not
@@ -191,6 +209,11 @@ export interface AgentOptions {
     onSkillsChanged?: () => Promise<unknown>;
     /** Restricts where writes may land. A policy gate, not an OS sandbox. */
     workspace?: WorkspacePolicy;
+    /**
+     * Who can host a session in a new worktree. A getter, because the frontend
+     * wires it after the harness — and so the agent it builds — already exists.
+     */
+    worktreeLauncher?: () => WorktreeLauncher | undefined;
     /** Enable provider prompt caching where the model supports it. */
     cache?: boolean;
     agentId?: string;
@@ -200,8 +223,38 @@ export interface AgentOptions {
     onAudit?: (event: RuntimeAuditEvent) => void;
     /** Internal host lifecycle accounting; inherited by subagents. */
     onRunStart?: () => () => void;
+    /**
+     * Who starts a turn to read in background results that end while this agent
+     * is idle. A getter, like worktreeLauncher, because the frontend wires it
+     * after the agent exists. Without one, background tasks are not offered:
+     * a result arriving after the run had ended would reach nobody.
+     */
+    taskWaker?: () => ((sessionId: string) => void) | undefined;
+    /** How many background tasks run at once; the rest queue. */
+    maxBackgroundTasks?: number;
+    /**
+     * Give a subagent its own browser and computer, so it never drives the
+     * parent's tabs or acts under the parent's window leases. Rebinds the
+     * per-conversation tools already in `tools`; `release` closes them again.
+     */
+    equipSubagent?: (sessionId: string, label: string, tools: ToolRegistry) => SubagentEquipment;
+    /**
+     * The conversation this agent's permission cards belong to. A subagent's
+     * own session is invisible to every frontend, so its questions are placed
+     * in the conversation that started it.
+     */
+    interactionSessionId?: string;
+    /** Who is asking, on those cards: "general: fix the flaky test". */
+    interactionLabel?: string;
     logger?: Logger;
 }
+export interface SubagentEquipment {
+    /** Replaces the parent's run accounting, which would release the parent's leases. */
+    onRunStart?: () => () => void;
+    /** Rebind its tools into another registry: the same browser and computer, for a later run. */
+    bind?(tools: ToolRegistry): void;
+    release(): Promise<void>;
+}
 /**
  * Notes attached to messages still in the transcript.
  *
@@ -218,6 +271,22 @@ export declare function recalledInTranscript(messages: readonly Message[]): Set<
  * same regardless of which model is selected — including when the model
  * changes partway through a session.
  */
+/** How a conversation fills the model's window; see Agent.contextBreakdown(). */
+export interface ContextBreakdown {
+    /** Tokens in use: measured from the last request when there was one. */
+    total: number;
+    window: number;
+    /** Estimated: the system prompt, with skills, memory and project notes. */
+    system: number;
+    /** Estimated: the definitions of the tools offered to the model. */
+    tools: number;
+    /** The rest of the total: the conversation itself. */
+    messages: number;
+    /** Whether `total` came from the provider rather than an estimate. */
+    measured: boolean;
+    /** Tokens at which automatic compaction fires; absent when it is off. */
+    compactAt?: number;
+}
 export declare class Agent implements ToolHost {
     readonly session: Session;
     readonly tools: ToolRegistry;
@@ -248,6 +317,18 @@ export declare class Agent implements ToolHost {
     private pluginSections;
     /** Recall over `memory` for agents embedded without a plugin host. */
     private legacyMemory?;
+    /** Subagents running in the background; made on first use. */
+    private background?;
+    private wakeTimer?;
+    /** Frontends watching background tasks, kept until the tasks exist. */
+    private readonly changeListeners;
+    /** What each background task was asked, and its subagent once it has one. */
+    private readonly taskStates;
+    private restoring?;
+    private saveTimer?;
+    /** Closed or deleted: nothing more is saved, and nothing more starts. */
+    private tasksClosed;
+    private saveChain;
     constructor(opts: AgentOptions);
     /**
      * Announce a model switch so a UI can render it and hooks can react.
@@ -295,14 +376,155 @@ export declare class Agent implements ToolHost {
      * tools ask rather than each re-deriving a notion of "inside the project".
      */
     resolvePath(input: string, access: "read" | "write"): string;
+    startWorktree(opts: WorktreeStartOptions): Promise<WorktreeStartResult>;
     listSubagentTypes(): Array<{
         name: string;
         description: string;
+        readOnly?: boolean;
+        isolation?: "worktree";
     }>;
     runSubagent(opts: SubagentRunOptions): Promise<SubagentRunResult>;
+    /**
+     * Subagents running behind this conversation, offered only while someone
+     * can start a turn to read their results in. Once any exist they stay
+     * reachable, so they can still be listed, messaged and stopped.
+     */
+    get backgroundTasks(): BackgroundTaskHost | undefined;
+    /** A task's conversation so far, for a frontend to show. */
+    backgroundTranscript(id: string): readonly Message[] | undefined;
+    /** Every change to a background task, for a frontend to redraw from. */
+    onBackgroundChange(listener: (task: BackgroundTaskView) => void): () => void;
+    /**
+     * The conversation is being closed, not ended: write its tasks down as they
+     * stand, then stop them. Opened again, the ones that were running come back
+     * interrupted and can be followed up — as after a restart.
+     */
+    closeBackgroundTasks(): Promise<void>;
+    /**
+     * The conversation is being deleted: stop its tasks and write nothing more.
+     * Resolves once a write already under way has landed, so deleting the
+     * store afterwards cannot be undone by it.
+     */
+    discardBackgroundTasks(): Promise<void>;
+    private endBackgroundTasks;
+    private backgroundAvailable;
+    private tasks;
+    /**
+     * A background task's subagent, made for each run and let go after it.
+     *
+     * Between runs a task holds only its conversation and, if it changed
+     * anything, its worktree: no browser, no claim on the computer, no agent.
+     * A follow-up — or the first one after a restart — builds the subagent
+     * again from those, so both paths are the same path.
+     */
+    private backgroundSpec;
+    /**
+     * Put back the background tasks this conversation had before a restart.
+     *
+     * Called by a frontend when it opens the conversation; safe to call again.
+     * A task that was still running when the app closed comes back as failed
+     * and says why — its subagent's process is gone — but keeps its
+     * conversation, so a follow-up carries on from where it stopped. A result
+     * nobody had been told about is still read in with the next turn.
+     */
+    restoreBackgroundTasks(): Promise<number>;
+    /** Write the tasks down a moment after they change, so a burst is one write. */
+    private scheduleSave;
+    /**
+     * One write at a time, in order. Each takes its snapshot when its turn
+     * comes, so a later state is never overwritten by an earlier one landing
+     * last — a task that ended would come back as running.
+     */
+    private saveTasks;
+    private writeTasks;
+    private scheduleWake;
+    /**
+     * Read the results of background tasks that have ended into the
+     * conversation, as one message saying what is still running.
+     *
+     * Synthetic, like a goal nudge: nobody typed it, so it skips the prompt hook
+     * and memory recall, and never titles the session.
+     */
+    private takeNotices;
+    /** Where this agent's permission cards go, and who they say is asking. */
+    private interactionPlace;
+    /** A subagent ready to run: its agent, the tree it works in, what it holds. */
+    private prepareSubagent;
+    /**
+     * One run of a subagent, to its end: its first prompt, or a later message.
+     *
+     * `report` is there only for a background task: it is what lets a look at
+     * the task say what the subagent is doing now.
+     */
+    private runChild;
+    /**
+     * One run of a subagent whose loop is an external agent's (ACP).
+     *
+     * The child session is still kept, as the record of the task: the prompt
+     * and the agent's answer go into it, so a background task's transcript and
+     * a follow-up after a restart read the same as any other subagent's. The
+     * agent itself starts fresh each run, so what came before rides in the
+     * prompt.
+     */
+    private runExternalChild;
+    /**
+     * File access for an external agent, through this agent's workspace policy:
+     * reads where ours may read, writes where ours may write, nowhere else.
+     */
+    externalFs(): AcpFileSystem;
+    /**
+     * `@claude …`: a message addressed to an external agent by name.
+     *
+     * Only an agent with an ACP runtime answers to this, and only at the start
+     * of what was typed — or of the paragraph after a reference note, which the
+     * page puts above the prompt. The note stays with the message; the name
+     * does not.
+     */
+    private directTarget;
+    /**
+     * A turn answered by an external agent instead of the model.
+     *
+     * What makes `@claude` worth having: the message goes straight to the
+     * user's own Claude Code, so it is paid for by their Claude account and
+     * nothing is spent on this harness's model in between. The agent's reply
+     * streams into the conversation as text, its tool calls as tool cards, its
+     * questions as the usual permission card; the exchange is kept as an
+     * ordinary user/assistant pair, and the agent's session id rides on the
+     * reply so the next `@claude` picks up where this one left off.
+     */
+    private runDirect;
+    /**
+     * This conversation's MCP servers, in the shape ACP's `session/new` takes,
+     * so an external agent works with the same tools. HTTP ones are filtered
+     * out later for an agent that does not take them.
+     */
+    private forwardedMcpServers;
+    /**
+     * An external agent's own tool call, put to the person the way this
+     * harness's calls are — the same card, placed in the conversation that
+     * started the task and labelled with who is asking. Plan mode and a
+     * read-only workspace refuse; bypass allows, as it would for our own tools.
+     */
+    askForExternal(title: string, input: unknown, toolCallId: string, signal: AbortSignal | undefined, from?: string): Promise<boolean | PermissionAnswer>;
+    /** What a subagent left in its worktree, when it left anything. */
+    private worktreeNote;
+    /**
+     * A subagent is finished with: its browser and computer go, and a worktree
+     * it changed nothing in is removed. One that it changed is kept — the
+     * parent has to decide what happens to that work.
+     */
+    private disposeChild;
+    private dropIfUntouched;
     run(input: string | Message[], runOpts?: {
         signal?: AbortSignal;
     }): AsyncGenerator<AgentEvent, void, void>;
+    /**
+     * Where a reply ends with a goal still active: ask for more work.
+     *
+     * Returns whether the loop should go on. A model that keeps stopping short
+     * of its goal gets a bounded number of reminders, not an endless supply.
+     */
+    private pushTowardGoal;
     private ingestInput;
     /**
      * Put what the user said into the conversation, as its own message.
@@ -343,12 +565,46 @@ export declare class Agent implements ToolHost {
     private scheduleExtraction;
     /** Where the next end-of-run extraction starts, clamped to the transcript. */
     private extractedUpTo;
+    /**
+     * How full the model's window is, in tokens: what the last request measured,
+     * or, before one has (a new or reopened conversation), an estimate of the
+     * next request — system prompt and tools included, which are a large share
+     * of a short conversation.
+     */
+    contextTokens(): number;
+    /**
+     * The window, split the way the context panel draws it. Providers report one
+     * number for the prompt, so the system prompt and the tool definitions are
+     * estimated and the messages are what is left of the measured total; until
+     * something is measured all three are estimates.
+     */
+    contextBreakdown(): ContextBreakdown;
+    private contextEstimate;
+    /**
+     * Compact now, whatever the window says: the /compact command. Goes through
+     * the same path as the automatic kind, so what it drops is archived for
+     * recall and handed to memory extraction rather than simply discarded.
+     * Returns what happened, or undefined when there was nothing safe to cut.
+     */
+    compactNow(): Promise<AgentEvent | undefined>;
     private maybeCompact;
+    /**
+     * The tools offered to the model: the goal tool only while there is a goal,
+     * and the computer tools only while this conversation has Computer Use on.
+     */
+    private visibleTools;
     private systemPrompt;
     private buildRequest;
     /** Consume the provider stream, emitting deltas and assembling the message. */
     private streamAssistant;
     private executeCalls;
     private executeOne;
+    /**
+     * Ask about a write the workspace policy would refuse.
+     *
+     * Bypass mode approves it as it approves everything else. Read-only and plan
+     * mode refuse it, as does a frontend with no way to ask.
+     */
+    private askOutsideRoots;
     private checkPermission;
 }