nexus-agentd 0.2.5 → 0.3.0

package/dist/session/admin-runs.d.ts

@@ -0,0 +1,73 @@
+import type { AgentdAgentConfig, AgentdRunControls, AgentdPendingResponse, AgentdRunDetail, AgentdSessionState, AgentdSessionView } from '../types.js';
+export type { AgentdRunControls };
+export type AdminRunControls = AgentdRunControls;
+export interface AdminRunOperationResult {
+    run: AgentdRunDetail;
+    controls: AdminRunControls;
+    state: AgentdSessionState;
+    runId: string;
+    sessionId: string;
+    retryOfRunId?: string;
+}
+/**
+ * Quota state reserved for a retry that is about to create a new session.
+ * The reservation is bound as soon as the new session exists so lifecycle
+ * events can release each resource independently.
+ */
+export interface AdminRetryReservation {
+    bind(sessionId: string): void;
+    release(): void;
+}
+export type AdminRetryReservationFactory = (ownerKeyId: string) => AdminRetryReservation;
+export interface AdminRunSession {
+    readonly id: string;
+    readonly state: AgentdSessionState;
+    readonly ownerKeyId: string;
+    snapshot(): AgentdSessionView;
+    runtimeAvailable(): boolean;
+    cancel(): Promise<void>;
+    resolvePending(response: AgentdPendingResponse, attachmentIds?: string[]): Promise<void>;
+}
+export interface AdminRunOptions {
+    getRun(runId: string): AgentdRunDetail;
+    getSession(sessionId: string): AdminRunSession | undefined;
+    getAgent(agentId: string): AgentdAgentConfig | undefined;
+    getOwnerKeyId(runId: string): string | undefined;
+    withSessionLock<T>(sessionId: string, operation: () => Promise<T>): Promise<T>;
+    startRetry(run: AgentdRunDetail, ownerKeyId: string, reservation?: AdminRetryReservation): Promise<{
+        runId: string;
+        sessionId: string;
+    }>;
+    markRetryOf?(newRunId: string, oldRunId: string): unknown;
+    requestError(status: number, message: string): Error;
+    /** Optional bounds/clock overrides for embedding and deterministic tests. */
+    maxRetryRecords?: number;
+    retryRecordTtlMs?: number;
+    now?: () => number;
+}
+/**
+ * Administrator operations are keyed by persisted run IDs rather than API
+ * keys.  The session identity check is repeated inside the per-session lock
+ * immediately before every action; an old run can therefore never cancel or
+ * answer a newer turn on the same session.
+ */
+export declare class AdminRunManager {
+    private readonly options;
+    private retryRecords;
+    private retryRelations;
+    private readonly maxRetryRecords;
+    private readonly retryRecordTtlMs;
+    private readonly now;
+    constructor(options: AdminRunOptions);
+    getRunControls(runId: string): AdminRunControls;
+    cancelRun(runId: string): Promise<AdminRunOperationResult>;
+    respondRun(runId: string, response: AgentdPendingResponse, attachmentIds?: string[]): Promise<AdminRunOperationResult>;
+    retryRun(runId: string, reserveRetry?: AdminRetryReservationFactory): Promise<AdminRunOperationResult>;
+    retryOfRunId(runId: string): string | undefined;
+    private currentRetryRecord;
+    private pruneRetryState;
+    private dropRetryRecord;
+    private dropRetryRelation;
+    private assertCurrent;
+    private resultFor;
+}

package/dist/session/admin-runs.js

@@ -0,0 +1,297 @@
+const DEFAULT_MAX_RETRY_RECORDS = 512;
+const DEFAULT_RETRY_RECORD_TTL_MS = 24 * 60 * 60 * 1000;
+/**
+ * Administrator operations are keyed by persisted run IDs rather than API
+ * keys.  The session identity check is repeated inside the per-session lock
+ * immediately before every action; an old run can therefore never cancel or
+ * answer a newer turn on the same session.
+ */
+export class AdminRunManager {
+    options;
+    retryRecords = new Map();
+    retryRelations = new Map();
+    maxRetryRecords;
+    retryRecordTtlMs;
+    now;
+    constructor(options) {
+        this.options = options;
+        this.maxRetryRecords = positiveInteger(options.maxRetryRecords, DEFAULT_MAX_RETRY_RECORDS);
+        this.retryRecordTtlMs = positiveInteger(options.retryRecordTtlMs, DEFAULT_RETRY_RECORD_TTL_MS);
+        this.now = options.now || Date.now;
+    }
+    getRunControls(runId) {
+        this.pruneRetryState();
+        const run = this.options.getRun(runId);
+        const session = this.options.getSession(run.sessionId);
+        const snapshot = session?.snapshot();
+        const current = Boolean(snapshot && snapshot.runId === run.id);
+        const effectiveState = current ? snapshot.state : run.state;
+        const active = isActive(effectiveState);
+        const pendingRequest = current && snapshot?.pendingRequest
+            ? structuredClone(snapshot.pendingRequest)
+            : undefined;
+        let unavailableReason;
+        // A terminal historical run does not need its in-memory session in
+        // order to be retried. Session availability only explains why the
+        // current active turn cannot be controlled. A session may already be
+        // processing a newer turn while an older terminal run is retried in
+        // its own session.
+        if (isActive(run.state)) {
+            if (!session) {
+                unavailableReason = 'The run session is no longer available';
+            }
+            else if (!current) {
+                unavailableReason = 'The run is no longer the current session turn';
+            }
+            else if (!session.runtimeAvailable()) {
+                unavailableReason = 'Agent runtime is unavailable';
+            }
+        }
+        let canRetry = isTerminal(run.state);
+        if (canRetry && run.taskTruncated) {
+            canRetry = false;
+            unavailableReason =
+                'This run cannot be retried because its task record was truncated';
+        }
+        else if (canRetry && (run.inputAttachmentCount || 0) > 0) {
+            canRetry = false;
+            unavailableReason =
+                'This run cannot be retried because it used input attachments';
+        }
+        else if (canRetry) {
+            const agent = this.options.getAgent(run.agentId);
+            if (!agent || agent.enabled === false) {
+                canRetry = false;
+                unavailableReason = 'The configured agent is unavailable';
+            }
+        }
+        const retryRecord = this.currentRetryRecord(run.id);
+        if (canRetry && retryRecord?.status === 'pending') {
+            canRetry = false;
+            unavailableReason = 'Retry is already in progress for this run';
+        }
+        return {
+            canCancel: current && active && Boolean(session?.runtimeAvailable()),
+            canRetry,
+            ...(pendingRequest ? { pendingRequest } : {}),
+            ...(unavailableReason ? { unavailableReason } : {})
+        };
+    }
+    async cancelRun(runId) {
+        const run = this.options.getRun(runId);
+        return this.options.withSessionLock(run.sessionId, async () => {
+            const current = this.assertCurrent(runId);
+            if (!isActive(current.state)) {
+                throw this.options.requestError(409, 'The run is no longer active');
+            }
+            if (!current.runtimeAvailable()) {
+                throw this.options.requestError(409, 'Agent runtime is unavailable');
+            }
+            await current.cancel();
+            return this.resultFor(runId);
+        });
+    }
+    async respondRun(runId, response, attachmentIds = []) {
+        const run = this.options.getRun(runId);
+        return this.options.withSessionLock(run.sessionId, async () => {
+            const current = this.assertCurrent(runId);
+            if (!current.runtimeAvailable()) {
+                throw this.options.requestError(409, 'Agent runtime is unavailable');
+            }
+            if (!current.snapshot().pendingRequest) {
+                throw this.options.requestError(409, 'Pending request is no longer available');
+            }
+            await current.resolvePending(response, attachmentIds);
+            return this.resultFor(runId);
+        });
+    }
+    async retryRun(runId, reserveRetry) {
+        this.pruneRetryState();
+        const existing = this.currentRetryRecord(runId);
+        if (existing) {
+            if (existing.status === 'pending') {
+                throw this.options.requestError(409, 'Retry is already in progress for this run');
+            }
+            return this.resultFor(existing.newRunId, existing.retryOfRunId, existing.sessionId);
+        }
+        const run = this.options.getRun(runId);
+        if (!isTerminal(run.state)) {
+            throw this.options.requestError(409, 'Only terminal runs can be retried');
+        }
+        if (run.taskTruncated) {
+            throw this.options.requestError(409, 'This run cannot be retried because its task record was truncated');
+        }
+        if ((run.inputAttachmentCount || 0) > 0) {
+            throw this.options.requestError(409, 'This run cannot be retried because it used input attachments');
+        }
+        // Set this synchronously before the first await.  A second request in
+        // the same event-loop turn therefore receives 409 instead of creating
+        // another session.
+        const timestamp = this.now();
+        this.retryRecords.set(runId, {
+            retryOfRunId: runId,
+            status: 'pending',
+            createdAt: timestamp,
+            updatedAt: timestamp
+        });
+        let started;
+        let reservation;
+        try {
+            const ownerKeyId = this.options.getOwnerKeyId(runId);
+            if (!ownerKeyId) {
+                throw this.options.requestError(409, 'The original run owner is unavailable');
+            }
+            // The record above is the synchronous deduplication gate.  Only
+            // after it succeeds may the caller reserve resources for a new
+            // retry; a completed duplicate therefore never consumes quota.
+            reservation = reserveRetry?.(ownerKeyId);
+            started = await this.options.startRetry(run, ownerKeyId, reservation);
+            reservation?.bind(started.sessionId);
+            this.retryRelations.set(started.runId, runId);
+            try {
+                void Promise.resolve(this.options.markRetryOf?.(started.runId, runId)).catch(() => undefined);
+            }
+            catch {
+                // The in-memory relation still makes this attempt dedupable.
+                // Persistence failures must not turn a successfully started
+                // task into an apparent retry failure.
+            }
+            this.retryRecords.set(runId, {
+                retryOfRunId: runId,
+                status: 'succeeded',
+                newRunId: started.runId,
+                sessionId: started.sessionId,
+                createdAt: timestamp,
+                updatedAt: this.now()
+            });
+            this.pruneRetryState();
+            return this.resultFor(started.runId, runId, started.sessionId);
+        }
+        catch (error) {
+            reservation?.release();
+            this.dropRetryRecord(runId);
+            if (started)
+                this.dropRetryRelation(started.runId, runId);
+            throw error;
+        }
+    }
+    retryOfRunId(runId) {
+        this.pruneRetryState();
+        const sourceRunId = this.retryRelations.get(runId);
+        if (!sourceRunId)
+            return undefined;
+        try {
+            this.options.getRun(runId);
+            return sourceRunId;
+        }
+        catch (error) {
+            if (!isMissingRunError(error))
+                throw error;
+            const record = this.retryRecords.get(sourceRunId);
+            if (record?.newRunId === runId) {
+                this.dropRetryRecord(sourceRunId, record);
+            }
+            else {
+                this.dropRetryRelation(runId, sourceRunId);
+            }
+            return undefined;
+        }
+    }
+    currentRetryRecord(runId) {
+        const record = this.retryRecords.get(runId);
+        if (!record || record.status === 'pending')
+            return record;
+        if (!record.newRunId) {
+            this.dropRetryRecord(runId, record);
+            return undefined;
+        }
+        try {
+            this.options.getRun(record.newRunId);
+            return record;
+        }
+        catch (error) {
+            if (!isMissingRunError(error))
+                throw error;
+            this.dropRetryRecord(runId, record);
+            return undefined;
+        }
+    }
+    pruneRetryState() {
+        const now = this.now();
+        for (const [runId, record] of this.retryRecords) {
+            if (record.status === 'succeeded' &&
+                now - record.updatedAt >= this.retryRecordTtlMs) {
+                this.dropRetryRecord(runId, record);
+            }
+        }
+        if (this.retryRecords.size <= this.maxRetryRecords)
+            return;
+        const succeeded = Array.from(this.retryRecords.entries())
+            .filter(([, record]) => record.status === 'succeeded')
+            .sort((left, right) => left[1].updatedAt - right[1].updatedAt);
+        for (const [runId, record] of succeeded) {
+            if (this.retryRecords.size <= this.maxRetryRecords)
+                break;
+            this.dropRetryRecord(runId, record);
+        }
+    }
+    dropRetryRecord(runId, record) {
+        const current = this.retryRecords.get(runId);
+        if (!current || (record && current !== record))
+            return;
+        this.retryRecords.delete(runId);
+        if (current.newRunId) {
+            this.dropRetryRelation(current.newRunId, runId);
+        }
+    }
+    dropRetryRelation(newRunId, sourceRunId) {
+        if (this.retryRelations.get(newRunId) === sourceRunId) {
+            this.retryRelations.delete(newRunId);
+        }
+    }
+    assertCurrent(runId) {
+        const run = this.options.getRun(runId);
+        const session = this.options.getSession(run.sessionId);
+        if (!session) {
+            throw this.options.requestError(409, 'The run session is no longer available');
+        }
+        const snapshot = session.snapshot();
+        if (snapshot.runId !== runId) {
+            throw this.options.requestError(409, 'The run is no longer the current session turn');
+        }
+        return session;
+    }
+    resultFor(runId, retryOfRunId, sessionId) {
+        const run = this.options.getRun(runId);
+        const controls = this.getRunControls(runId);
+        return {
+            run: structuredClone(run),
+            controls,
+            state: run.state,
+            runId: run.id,
+            sessionId: sessionId || run.sessionId,
+            ...(retryOfRunId ? { retryOfRunId } : {})
+        };
+    }
+}
+function positiveInteger(value, fallback) {
+    return Number.isFinite(value) && Number(value) > 0
+        ? Math.floor(Number(value))
+        : fallback;
+}
+function isMissingRunError(error) {
+    if (isRecord(error) && error.status === 404)
+        return true;
+    return error instanceof Error && /run not found/i.test(error.message);
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+function isActive(state) {
+    return (state === 'running' ||
+        state === 'input_required' ||
+        state === 'permission_required');
+}
+function isTerminal(state) {
+    return state === 'completed' || state === 'failed' || state === 'canceled';
+}

package/dist/session/admission.d.ts

@@ -0,0 +1,32 @@
+import type { AgentdSessionState } from '../types.js';
+export interface AdmissionSession {
+    readonly id: string;
+    readonly state: AgentdSessionState;
+    readonly updatedAt: number;
+    dispose(): Promise<void>;
+}
+export interface SessionAdmissionOptions {
+    maxSessions(): number;
+    sessionCount(): number;
+    sessions(): Iterable<AdmissionSession>;
+    isCurrent(session: AdmissionSession): boolean;
+    withSessionLock<T>(id: string, operation: () => Promise<T>): Promise<T>;
+    removeSession(id: string): void;
+    requestError(status: number, message: string): Error;
+}
+/**
+ * Serialises admission decisions and owns the pending-create reservation.
+ * A reservation is held until the session has been inserted, so concurrent
+ * creates cannot temporarily exceed maxSessions while an ACP process starts.
+ */
+export declare class SessionAdmission {
+    private readonly options;
+    private pendingCreates;
+    private closing;
+    constructor(options: SessionAdmissionOptions);
+    markClosing(): void;
+    isClosing(): boolean;
+    pendingCount(): number;
+    reserve(): Promise<() => void>;
+    ensureCapacity(): Promise<void>;
+}

package/dist/session/admission.js

@@ -0,0 +1,62 @@
+/**
+ * Serialises admission decisions and owns the pending-create reservation.
+ * A reservation is held until the session has been inserted, so concurrent
+ * creates cannot temporarily exceed maxSessions while an ACP process starts.
+ */
+export class SessionAdmission {
+    options;
+    pendingCreates = 0;
+    closing = false;
+    constructor(options) {
+        this.options = options;
+    }
+    markClosing() {
+        this.closing = true;
+    }
+    isClosing() {
+        return this.closing;
+    }
+    pendingCount() {
+        return this.pendingCreates;
+    }
+    async reserve() {
+        if (this.closing) {
+            throw this.options.requestError(503, 'Gateway is shutting down');
+        }
+        await this.ensureCapacity();
+        this.pendingCreates++;
+        let reserved = true;
+        return () => {
+            if (!reserved)
+                return;
+            reserved = false;
+            this.pendingCreates--;
+        };
+    }
+    async ensureCapacity() {
+        const limit = this.options.maxSessions();
+        if (this.options.sessionCount() + this.pendingCreates < limit)
+            return;
+        const terminal = Array.from(this.options.sessions())
+            .filter((session) => isTerminal(session.state))
+            .sort((left, right) => left.updatedAt - right.updatedAt);
+        while (this.options.sessionCount() + this.pendingCreates >= limit &&
+            terminal.length) {
+            const session = terminal.shift();
+            await this.options.withSessionLock(session.id, async () => {
+                if (!this.options.isCurrent(session) ||
+                    !isTerminal(session.state)) {
+                    return;
+                }
+                await session.dispose();
+                this.options.removeSession(session.id);
+            });
+        }
+        if (this.options.sessionCount() + this.pendingCreates >= limit) {
+            throw this.options.requestError(429, 'Session capacity has been reached');
+        }
+    }
+}
+function isTerminal(state) {
+    return state === 'completed' || state === 'failed' || state === 'canceled';
+}

package/dist/session/readiness.d.ts

@@ -0,0 +1,33 @@
+import type { AgentDriver } from '../drivers/index.js';
+import type { AgentdAgentView, AgentdConfig } from '../types.js';
+/**
+ * Dependencies needed by the readiness cache.  The error factory lives in
+ * session.ts so callers still receive the gateway's normal request error type
+ * without making this helper depend on SessionManager.
+ */
+export interface ReadinessOptions {
+    requestError(status: number, message: string): Error;
+}
+/**
+ * Per-agent readiness probes are deliberately kept outside SessionManager.
+ * Besides making the manager easier to reason about, this keeps an in-flight
+ * probe shared by all callers and bounds the number of child processes or
+ * remote card requests started by a dashboard refresh.
+ */
+export declare class SessionReadiness {
+    private readonly options;
+    private readonly maxConcurrent;
+    private readonly cacheMs;
+    private config;
+    private drivers;
+    private cache;
+    private inFlight;
+    private generation;
+    private activeProbes;
+    private waiters;
+    constructor(config: AgentdConfig, drivers: Map<string, AgentDriver>, options: ReadinessOptions, maxConcurrent?: number, cacheMs?: number);
+    reconfigure(config: AgentdConfig, drivers: Map<string, AgentDriver>): void;
+    listAgents(agentIds?: Set<string>, force?: boolean): Promise<AgentdAgentView[]>;
+    private withProbeSlot;
+    private defaultWorkspace;
+}

package/dist/session/readiness.js

@@ -0,0 +1,174 @@
+import { probeA2AAgent } from '../a2a/runtime.js';
+/**
+ * Per-agent readiness probes are deliberately kept outside SessionManager.
+ * Besides making the manager easier to reason about, this keeps an in-flight
+ * probe shared by all callers and bounds the number of child processes or
+ * remote card requests started by a dashboard refresh.
+ */
+export class SessionReadiness {
+    options;
+    maxConcurrent;
+    cacheMs;
+    config;
+    drivers;
+    cache = new Map();
+    inFlight = new Map();
+    generation = 0;
+    activeProbes = 0;
+    waiters = [];
+    constructor(config, drivers, options, maxConcurrent = 4, cacheMs = 20_000) {
+        this.options = options;
+        this.maxConcurrent = maxConcurrent;
+        this.cacheMs = cacheMs;
+        this.config = config;
+        this.drivers = drivers;
+    }
+    reconfigure(config, drivers) {
+        const probesChanged = JSON.stringify([this.config.agents, this.config.workspaceRoots]) !==
+            JSON.stringify([config.agents, config.workspaceRoots]);
+        this.config = config;
+        this.drivers = drivers;
+        if (probesChanged) {
+            this.generation++;
+            this.cache.clear();
+            // Existing probes are allowed to settle.  The generation check
+            // below prevents their results from becoming the new cache.
+        }
+    }
+    async listAgents(agentIds, force = false) {
+        const now = Date.now();
+        const catalogGeneration = this.generation;
+        const agents = await Promise.all(Object.entries(this.config.agents)
+            .filter(([id]) => !agentIds || agentIds.has(id))
+            .map(async ([id, config]) => {
+            const cached = this.cache.get(id);
+            if (cached &&
+                now - cached.checkedAt < (force ? 5_000 : this.cacheMs)) {
+                return structuredClone(cached.agent);
+            }
+            const existing = this.inFlight.get(id);
+            if (existing) {
+                const value = await existing.promise;
+                if (existing.generation !== this.generation) {
+                    throw this.options.requestError(409, 'Agent configuration changed; retry readiness');
+                }
+                return structuredClone(value);
+            }
+            const generation = this.generation;
+            const probeAgent = async () => {
+                if (config.protocol === 'a2a') {
+                    return probeA2AAgent(id, config);
+                }
+                if (config.enabled === false) {
+                    return {
+                        id,
+                        name: config.name || id,
+                        description: config.description,
+                        protocol: 'acp',
+                        driver: config.driver,
+                        ready: false,
+                        enabled: false,
+                        workspace: this.defaultWorkspace(id),
+                        error: 'Agent is disabled',
+                        checkedAt: Date.now()
+                    };
+                }
+                const driver = this.drivers.get(id);
+                if (!driver) {
+                    return {
+                        id,
+                        name: config.name || id,
+                        description: config.description,
+                        protocol: 'acp',
+                        driver: config.driver,
+                        ready: false,
+                        enabled: true,
+                        workspace: this.defaultWorkspace(id),
+                        error: 'ACP driver is unavailable',
+                        checkedAt: Date.now()
+                    };
+                }
+                const startedAt = Date.now();
+                try {
+                    const probe = await driver.probe();
+                    return {
+                        ...probe,
+                        protocol: 'acp',
+                        driver: config.driver,
+                        enabled: true,
+                        workspace: this.defaultWorkspace(id),
+                        checkedAt: Date.now(),
+                        responseMs: Date.now() - startedAt
+                    };
+                }
+                catch (error) {
+                    return {
+                        id,
+                        name: config.name || id,
+                        description: config.description,
+                        protocol: 'acp',
+                        driver: config.driver,
+                        ready: false,
+                        enabled: true,
+                        workspace: this.defaultWorkspace(id),
+                        error: errorMessage(error),
+                        checkedAt: Date.now(),
+                        responseMs: Date.now() - startedAt
+                    };
+                }
+            };
+            const pending = this.withProbeSlot(async () => {
+                if (generation !== this.generation) {
+                    throw this.options.requestError(409, 'Agent configuration changed; retry readiness');
+                }
+                return probeAgent();
+            });
+            this.inFlight.set(id, { generation, promise: pending });
+            try {
+                const agent = await pending;
+                if (generation === this.generation) {
+                    this.cache.set(id, {
+                        checkedAt: Date.now(),
+                        agent: structuredClone(agent)
+                    });
+                }
+                return agent;
+            }
+            finally {
+                if (this.inFlight.get(id)?.promise === pending) {
+                    this.inFlight.delete(id);
+                }
+            }
+        }));
+        if (catalogGeneration !== this.generation) {
+            throw this.options.requestError(409, 'Agent configuration changed; retry readiness');
+        }
+        agents.sort((left, right) => left.name.localeCompare(right.name));
+        return agents.map((agent) => structuredClone(agent));
+    }
+    async withProbeSlot(operation) {
+        if (this.activeProbes < this.maxConcurrent)
+            this.activeProbes++;
+        else
+            await new Promise((resolve) => this.waiters.push(resolve));
+        try {
+            return await operation();
+        }
+        finally {
+            const next = this.waiters.shift();
+            if (next)
+                next();
+            else
+                this.activeProbes--;
+        }
+    }
+    defaultWorkspace(agentId) {
+        const config = this.config.agents[agentId];
+        if (config?.protocol === 'a2a')
+            return '';
+        return config?.workspace || this.config.workspaceRoots[0] || '';
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/session-contract.d.ts

@@ -18,6 +18,7 @@ export interface AcpSessionSink extends AgentSessionSink {
     setAcpSessionId(id: string): void;
 }
 export interface AgentSessionRuntime {
+    isAvailable?(): boolean;
     start(workspace?: string): Promise<void>;
     prompt(message: string, attachments?: AgentdInputAttachment[]): Promise<void>;
     respondPending(response: AgentdPendingResponse | string, attachments?: AgentdInputAttachment[]): Promise<void>;