@camerontaylor/paseo-server 0.8.0-fork.1

package/dist/server/server/agent/providers/gjc-acp-agent.d.ts

@@ -0,0 +1,155 @@
+import type { SessionNotification } from "@agentclientprotocol/sdk";
+import type { Logger } from "pino";
+import type { AgentPromptInput, AgentSessionConfig, SteerActiveTurnOptions, SteerResult } from "../agent-sdk-types.js";
+import { ACPAgentSession, type ACPAgentSessionOptions, type ACPStopCorrelation, type ACPStopRecord } from "./acp-agent.js";
+import { GenericACPAgentClient } from "./generic-acp-agent.js";
+/**
+ * Fork-only GJC provider.
+ *
+ * GJC 0.15.5 runs turns the client did not start, so two things differ from a
+ * plain ACP session:
+ *
+ * 1. Ownerless activity has to be mirrored into Paseo with an explicit turn id,
+ *    because `gjcPhase` carries no turn id and `AgentManager` would otherwise
+ *    attribute the mirror's delayed terminal to whichever turn it knows about.
+ * 2. Stopping that ownerless turn cannot use ACP `session/cancel` proof alone:
+ *    the cancellation that reaches GJC is the `_gjc/sdk/control` terminal
+ *    `turn.abort`, so the stop gate needs a validated abort result plus a
+ *    post-stop authoritative idle, in either order.
+ *
+ * Foreground turns stay on the generic boundary and ACP `session/cancel`. The
+ * control extension is ownerless-only.
+ */
+type GjcAbortScope = "turn" | "owned";
+/** Resolves `GJC_ACP_ABORT_SCOPE` once per session. An unknown value refuses to start. */
+export declare function resolveGjcAbortScope(rawValue: string | undefined): GjcAbortScope;
+/**
+ * What one `turn.abort` response proved. `safe` is a terminal-safe stop for the
+ * requested scope; `conditional` is the `no_active_turn` no-effect result, which
+ * is only ever a second fact; `reject` leaves the stop installed.
+ */
+type GjcAbortVerdict = {
+    kind: "safe";
+    disposition: string;
+} | {
+    kind: "conditional";
+    disposition: string;
+} | {
+    kind: "reject";
+    disposition: string;
+    reason: string;
+};
+/**
+ * GJC 0.15.5 `terminalAbort` validation, matched to the shapes in
+ * `session-runtime.ts`. A failed control call arrives here too, as a resolved
+ * `{ok:false,error}` payload, and is a verdict like any other. Extra fields
+ * (documented `replay` metadata) are ignored.
+ */
+export declare function validateGjcTerminalAbortResult(result: unknown, scope: GjcAbortScope): GjcAbortVerdict;
+export interface GjcACPAgentClientOptions {
+    logger: Logger;
+    command: [string, ...string[]];
+    env?: Record<string, string>;
+    providerId?: string;
+    label?: string;
+    providerParams?: unknown;
+    waitForInitialCommands?: boolean;
+    initialCommandsWaitTimeoutMs?: number;
+    diagnosticPhaseTimeoutMs?: number;
+}
+/**
+ * Registry entry point for a custom ACP provider with `providerId:"gjc"`.
+ * Everything launch- and catalog-related stays in the generic client; only the
+ * session is substituted.
+ */
+export declare class GjcACPAgentClient extends GenericACPAgentClient {
+    protected createAgentSession(config: AgentSessionConfig, options: ACPAgentSessionOptions): ACPAgentSession;
+}
+export declare class GjcACPAgentSession extends ACPAgentSession {
+    private readonly abortScope;
+    /** Mirrors the base `closed` flag, which is not visible to subclasses. */
+    private ownClosed;
+    /** True inside the resume/replay window, where GJC publishes no phase edges. */
+    private replayingPhaseEdges;
+    private currentPhase;
+    private phaseRevision;
+    private mirror;
+    private ownerlessStop;
+    constructor(config: AgentSessionConfig, options: ACPAgentSessionOptions);
+    get configuredAbortScope(): GjcAbortScope;
+    sessionUpdate(params: SessionNotification): Promise<void>;
+    /**
+     * History replay is the one window where a phase edge must not move mirror or
+     * admission state: a resumed session replays a past transcript, and an
+     * autonomous turn from that transcript is not running now. GJC 0.15.5 emits
+     * no `gjcPhase` during replay, so this is containment rather than a live path.
+     */
+    initializeResumedSession(): Promise<void>;
+    interrupt(): Promise<void>;
+    /**
+     * The deny half of the §7 stop-kind router. The guards mirror `interrupt()`:
+     * a foreground turn keeps the generic boundary, an open ownerless mirror gets
+     * the ownerless stop (reusing it when the denial lands on an already-stopped
+     * mirror), and no stop-able turn falls through to the base router, which
+     * suppresses the cancellation write with the deny correlation attached.
+     */
+    protected stopTurnOnPermissionDenial(correlation: ACPStopCorrelation): Promise<void>;
+    /**
+     * The one ownerless stop operation, shared by `interrupt()` and the deny
+     * router: invalidates a displaced stop's staged successor, installs the
+     * provider-owned boundary synchronously, and issues the terminal abort
+     * without awaiting its response (issue-and-return).
+     */
+    private installOwnerlessStopAndAbort;
+    close(): Promise<void>;
+    steerActiveTurn(prompt: AgentPromptInput, options: SteerActiveTurnOptions): Promise<SteerResult>;
+    protected isProviderStopGateSatisfied(stop: ACPStopRecord): boolean;
+    protected describeProviderStopGate(stop: ACPStopRecord): string[];
+    /**
+     * One death path proof: the ownerless abort attempt still awaiting its
+     * response can never be answered by a dead transport, so it is settled as a
+     * reject through the ordinary result path. Newest-wins keeps a late reply
+     * for the same attempt from overwriting the death verdict.
+     */
+    protected recordProviderStopDeath(stop: ACPStopRecord, reason: string): void;
+    /**
+     * Two facts, either order: a validated terminal-safe abort result and a
+     * current eligible post-stop idle. `conditional` never counts alone. Named so
+     * the admission deadline can log which one is missing.
+     */
+    private unresolvedGjcStopFacts;
+    /**
+     * The session identity half of the base triple, through the read-only
+     * accessors a subclass gets. There is no connection-revision accessor, and
+     * `finishTurn` re-checks the full triple before delivering, so a stop
+     * captured on a replaced connection still cannot release a terminal here.
+     */
+    private gjcStopIdentityMatches;
+    private observeGjcPhase;
+    private handleWorkingEdge;
+    private handleIdleEdge;
+    /**
+     * Natural ownerless completion closes the mirror on the ordinary working→idle
+     * edge, unless the mirror's own stop boundary is what owns its terminal.
+     */
+    private closeMirrorNaturally;
+    /**
+     * Issue-and-return: the synchronous prefix (identity check, attempt
+     * revision, idempotency key, attempt log) runs before this returns, and the
+     * control request is dispatched without awaiting its response. gjc's own
+     * abort budget and the admission deadline are both 10 s while the manager
+     * waits only 2 s around `interrupt()`, so awaiting the response reports
+     * every healthy slow abort as a refused Stop. Both settlements attach here
+     * and record through `recordAbortResult`, which keeps newest-wins,
+     * validation, and release on one path: a resolution records its validated
+     * verdict; a rejection records `transport_rejected` and is logged. A late
+     * rejection is a recorded fact, not a user-visible failure — interrupt()
+     * has already returned — so it is never rethrown and never terminalizes the
+     * mirror turn.
+     */
+    private issueTerminalAbort;
+    private recordAbortResult;
+    private maybeReleaseOwnerlessStop;
+}
+export {};
+//# sourceMappingURL=gjc-acp-agent.d.ts.map