dsh-a2a-server 0.1.0

package/cordis.patch.yml

@@ -0,0 +1,30 @@
+# The layer this bundle contributes when a profile lists it.
+#
+# `isolation.workspaceRoot` has no safe default and must be supplied, and an
+# empty `peers` table means every request is answered 401 — both deliberate, so
+# an unconfigured install exposes nothing.
+#
+# REQUIRES ctx.webServer, which ships in `dsh-web-app`, NOT in `dsh-base`. On a
+# profile without it this row loads but stays PENDING (Cordis holds a plugin
+# whose injected services are absent), so nothing serves and nothing errors.
+- insert:
+    - id: a2a-server
+      name: dsh-a2a-server
+      config:
+        basePath: /a2a
+        protocolVersion: '0.3.0'
+        card:
+          name: dsh-harness
+          description: A DeepSeek Harness agent reachable over A2A.
+          public: true
+          skills: []
+        peers: {}
+        isolation:
+          # Default posture is isolation: each peer gets its own working
+          # directory, which also makes the cwd-equality authority in
+          # cross-session tooling separate peers for free. A deployment whose
+          # peers collaborate on one repository must say so explicitly.
+          workspaceMode: per-peer
+          workspaceRoot: !!js `${process.env.DSH_HOME ?? process.env.HOME}/a2a-workspaces`
+        push:
+          enabled: false

package/lib/config.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Plugin configuration schema.
+ *
+ * Every credential-shaped field carries a REFERENCE name resolved through
+ * `ctx.credentials`, never a value — the doctrine `dsh-credentials` states as
+ * "configuration carries references to secrets, never the secrets". A pasted
+ * token fails the POSIX-identifier check at load rather than silently becoming
+ * a reference nobody stored.
+ *
+ * @module dsh-a2a/config
+ */
+import Schema from '@deepseek-ai/schemastery';
+/** One authenticated peer and where its credential lives. */
+export interface PeerConfig {
+    /** Credential reference name, NOT the token itself. */
+    tokenEnv: string;
+}
+/**
+ * How peers are kept from reaching each other.
+ *
+ * DEFERRED — a tool deny-list (`session_search`, `session_event_search`,
+ * `session_trace`, `session_event_trace`, `session_event_read`, `list_agents`)
+ * plus a named `unsafeAllowCrossSessionSearch` escape hatch for single-peer
+ * deployments. Both were designed as defense in depth behind `workspaceMode`,
+ * and neither is declared here until it is enforced: a security knob that
+ * silently does nothing is worse than no knob at all.
+ */
+export interface IsolationConfig {
+    /**
+     * `per-peer` gives each identity its own cwd, which also makes the existing
+     * cwd-equality authority in cross-session tooling isolate them for free.
+     * `shared` is the collaborative posture and must be chosen deliberately.
+     */
+    workspaceMode: 'per-peer' | 'shared';
+    /** Parent directory in `per-peer` mode; the common cwd in `shared` mode. */
+    workspaceRoot: string;
+    /** Per-peer cwd overrides, e.g. pointing one trusted peer at a real repo. */
+    peerWorkspaces: Record<string, string>;
+}
+/** Agent Card content and exposure. */
+export interface CardConfig {
+    name: string;
+    description: string;
+    /** Serve the card without a credential, as discovery expects. */
+    public: boolean;
+    skills: {
+        id: string;
+        name: string;
+        description: string;
+        tags: string[];
+    }[];
+    provider?: {
+        organization: string;
+        url: string;
+    };
+}
+/**
+ * Terminal-state webhook callbacks.
+ *
+ * Only `enabled` exists so far, and only to answer the push methods with the
+ * spec's own `PushNotificationNotSupported` and to keep the Agent Card honest.
+ *
+ * DEFERRED — the sender itself, plus its SSRF fence
+ * (`allowPrivateNetworkCallbacks`, `allowInsecureCallbacks`) and
+ * `requestTimeoutMs`. Those knobs arrive with the code that honors them; a
+ * deployment must not be able to set `allowPrivateNetworkCallbacks: false` and
+ * believe something is enforcing it.
+ */
+export interface PushConfig {
+    /**
+     * Reserved. Turning this on today only changes which error the push methods
+     * return, so it stays documented as unimplemented.
+     */
+    enabled: boolean;
+}
+/** The whole plugin configuration. */
+export interface A2AServerConfig {
+    basePath: string;
+    publicUrl?: string;
+    protocolVersion: string;
+    /**
+     * Provider route for every agent this server creates. Optional so another
+     * `agent/request` listener may supply the target instead; a runnable
+     * composition needs one of the two.
+     */
+    provider?: string;
+    /** Model for every agent this server creates. */
+    model?: string;
+    card: CardConfig;
+    peers: Record<string, PeerConfig>;
+    trustedPeers?: string[];
+    rateLimitPerMinute: number;
+    maxContextTurns: number;
+    sendMode: 'block' | 'immediate';
+    blockTimeoutMs: number;
+    contextIdleTtlMs: number;
+    maxResidentContexts: number;
+    isolation: IsolationConfig;
+    push: PushConfig;
+}
+export declare const Config: Schema<A2AServerConfig>;
+/** A configuration mistake found before anything starts serving. */
+export declare class A2AConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Check the config's cross-field rules that a schema cannot express.
+ *
+ * Every failure here is a misconfiguration that would otherwise surface as a
+ * peer mysteriously receiving 401 forever, or as a workspace path escaping its
+ * root — both far worse than refusing to load.
+ * @param config - the validated configuration.
+ * @throws {A2AConfigError} when a peer name, credential reference, or path is unusable.
+ */
+export declare function assertConfigCoherent(config: A2AServerConfig): void;
+//# sourceMappingURL=config.d.ts.map

package/lib/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,MAAM,MAAM,0BAA0B,CAAA;AAQ7C,6DAA6D;AAC7D,MAAM,WAAW,UAAU;IACzB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,aAAa,EAAE,UAAU,GAAG,QAAQ,CAAA;IACpC,4EAA4E;IAC5E,aAAa,EAAE,MAAM,CAAA;IACrB,6EAA6E;IAC7E,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACvC;AAED,uCAAuC;AACvC,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,iEAAiE;IACjE,MAAM,EAAE,OAAO,CAAA;IACf,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAA;IAC3E,QAAQ,CAAC,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;CACjD;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,sCAAsC;AACtC,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,eAAe,EAAE,MAAM,CAAA;IACvB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,UAAU,CAAA;IAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IACjC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,eAAe,EAAE,MAAM,CAAA;IACvB,QAAQ,EAAE,OAAO,GAAG,WAAW,CAAA;IAC/B,cAAc,EAAE,MAAM,CAAA;IACtB,gBAAgB,EAAE,MAAM,CAAA;IACxB,mBAAmB,EAAE,MAAM,CAAA;IAC3B,SAAS,EAAE,eAAe,CAAA;IAC1B,IAAI,EAAE,UAAU,CAAA;CACjB;AAcD,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,eAAe,CA+CzC,CAAA;AAEF,oEAAoE;AACpE,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CA4BlE"}

package/lib/config.js

@@ -0,0 +1,110 @@
+/**
+ * Plugin configuration schema.
+ *
+ * Every credential-shaped field carries a REFERENCE name resolved through
+ * `ctx.credentials`, never a value — the doctrine `dsh-credentials` states as
+ * "configuration carries references to secrets, never the secrets". A pasted
+ * token fails the POSIX-identifier check at load rather than silently becoming
+ * a reference nobody stored.
+ *
+ * @module dsh-a2a/config
+ */
+import Schema from '@deepseek-ai/schemastery';
+/** A credential reference name: the shape `ctx.credentials` addresses. */
+const CREDENTIAL_REF = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** A peer name: also the workspace directory component, so no separators. */
+const PEER_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+/*
+ * DEFERRED configuration, removed rather than left inert:
+ *
+ * - `streamGranularity: 'message' | 'chunk'` — streaming currently emits only
+ *   committed assistant messages. The `chunk` mode needs an `assistant/chunk`
+ *   subscription and a decision about retried text reaching a peer.
+ * - `taskTimeoutMs` — the orphan-task watchdog that would fail a task stuck
+ *   non-terminal. Nothing sweeps for those yet.
+ *
+ * Both were in the design; neither is wired. They return with their code.
+ */
+export const Config = Schema.object({
+    basePath: Schema.string().default('/a2a'),
+    publicUrl: Schema.string(),
+    protocolVersion: Schema.string().default('0.3.0'),
+    provider: Schema.string(),
+    model: Schema.string(),
+    card: Schema.object({
+        name: Schema.string().default('dsh-harness'),
+        description: Schema.string().default('A DeepSeek Harness agent reachable over A2A.'),
+        public: Schema.boolean().default(true),
+        skills: Schema.array(Schema.object({
+            id: Schema.string().required(),
+            name: Schema.string().required(),
+            description: Schema.string().default(''),
+            tags: Schema.array(Schema.string()).default([]),
+        })).default([]),
+        // Both members default rather than being required: schemastery instantiates
+        // a nested object even when the deployment omits it, so a `required()` here
+        // would make an absent `provider` a validation failure.
+        provider: Schema.object({
+            organization: Schema.string().default(''),
+            url: Schema.string().default(''),
+        }),
+    }),
+    peers: Schema.dict(Schema.object({
+        tokenEnv: Schema.string().required(),
+    })).default({}),
+    trustedPeers: Schema.array(Schema.string()),
+    rateLimitPerMinute: Schema.natural().default(60),
+    maxContextTurns: Schema.natural().default(5),
+    sendMode: Schema.union(['block', 'immediate']).default('block'),
+    blockTimeoutMs: Schema.natural().default(60_000),
+    contextIdleTtlMs: Schema.natural().default(1_800_000),
+    maxResidentContexts: Schema.natural().default(64),
+    isolation: Schema.object({
+        workspaceMode: Schema.union(['per-peer', 'shared']).default('per-peer'),
+        workspaceRoot: Schema.string().required(),
+        peerWorkspaces: Schema.dict(Schema.string()).default({}),
+    }).required(),
+    push: Schema.object({
+        enabled: Schema.boolean().default(false),
+    }),
+});
+/** A configuration mistake found before anything starts serving. */
+export class A2AConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'A2AConfigError';
+    }
+}
+/**
+ * Check the config's cross-field rules that a schema cannot express.
+ *
+ * Every failure here is a misconfiguration that would otherwise surface as a
+ * peer mysteriously receiving 401 forever, or as a workspace path escaping its
+ * root — both far worse than refusing to load.
+ * @param config - the validated configuration.
+ * @throws {A2AConfigError} when a peer name, credential reference, or path is unusable.
+ */
+export function assertConfigCoherent(config) {
+    for (const [peer, entry] of Object.entries(config.peers)) {
+        if (!PEER_NAME.test(peer)) {
+            throw new A2AConfigError(`peer name "${peer}" must match ${String(PEER_NAME)}: it becomes a workspace directory component`);
+        }
+        if (!CREDENTIAL_REF.test(entry.tokenEnv)) {
+            throw new A2AConfigError(`peers.${peer}.tokenEnv must be a credential REFERENCE name (${String(CREDENTIAL_REF)}), not a token value`);
+        }
+    }
+    for (const trusted of config.trustedPeers ?? []) {
+        if (!(trusted in config.peers)) {
+            throw new A2AConfigError(`trustedPeers names "${trusted}", which is not declared in peers`);
+        }
+    }
+    for (const peer of Object.keys(config.isolation.peerWorkspaces)) {
+        if (!(peer in config.peers)) {
+            throw new A2AConfigError(`isolation.peerWorkspaces names "${peer}", which is not declared in peers`);
+        }
+    }
+    if (!config.basePath.startsWith('/')) {
+        throw new A2AConfigError(`basePath must start with "/": ${config.basePath}`);
+    }
+}
+//# sourceMappingURL=config.js.map

package/lib/config.js.map

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

package/lib/contexts.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The contextId → Activation registry and its residency policy.
+ *
+ * This is the biggest structural difference from `dsh-acp`. ACP has a stdio
+ * connection whose lifetime owns its sessions; HTTP has no connection lifetime
+ * at all, so residency must be an explicit policy. An **Activation** is one
+ * residency epoch for a contextId — the same word `ctx.subagents` uses for a
+ * continuable child's residency, and the same shape: evicting an Activation
+ * releases the AgentHandle while the durable Session stays, so the next message
+ * cold-resumes rather than starting over.
+ *
+ * @module dsh-a2a/contexts
+ */
+import type { Agent, AgentHandle } from '@deepseek-ai/dsh-agent';
+import type { A2AContextId, A2ATaskId } from './protocol/index.ts';
+import type { TaskSlot } from './tasks.ts';
+/** One resident contextId. */
+export interface Activation {
+    readonly contextId: A2AContextId;
+    readonly agent: Agent;
+    readonly handle: AgentHandle;
+    /** The authenticated peer that created this context. Ownership is by identity. */
+    readonly peer: string;
+    /** The resolved working directory this context's agent runs in. */
+    readonly cwd: string;
+    /** In-flight tasks, keyed by task id. FIFO order comes from the agent inbox. */
+    readonly slots: Map<A2ATaskId, TaskSlot>;
+    /** Last time a request touched this context, for idle eviction. */
+    lastTouchedAt: number;
+}
+/** Why a context lookup did not produce an Activation. */
+export type LookupFailure = 'unknown' | 'forbidden';
+/** Registry of resident contexts with LRU + idle eviction. */
+export declare class ContextRegistry {
+    private readonly maxResident;
+    private readonly idleTtlMs;
+    private readonly now;
+    private readonly activations;
+    /**
+     * @param maxResident - hard ceiling on resident contexts.
+     * @param idleTtlMs - how long an untouched, quiet context stays resident.
+     * @param now - clock injection point for tests.
+     */
+    constructor(maxResident: number, idleTtlMs: number, now?: () => number);
+    /** Every resident Activation, in insertion order. */
+    values(): Activation[];
+    /** How many contexts are currently resident. */
+    get size(): number;
+    /**
+     * Look up a context on behalf of an authenticated peer.
+     *
+     * A context owned by ANOTHER peer reports `forbidden`, and the caller must
+     * answer exactly as it answers `unknown` — otherwise a peer could enumerate
+     * which context ids exist by comparing the two responses.
+     * @param contextId - the id the peer presented.
+     * @param peer - the authenticated identity making the request.
+     * @returns the Activation, or why it is unavailable.
+     */
+    lookup(contextId: A2AContextId, peer: string): Activation | LookupFailure;
+    /**
+     * Register a freshly created or resumed Activation.
+     * @param activation - the Activation to hold.
+     */
+    add(activation: Activation): void;
+    /**
+     * Remove an Activation from the registry without disposing it.
+     * @param contextId - the context to forget.
+     * @returns the removed Activation, if it was resident.
+     */
+    remove(contextId: A2AContextId): Activation | undefined;
+    /** Forget every Activation and return them for the caller to dispose. */
+    drain(): Activation[];
+    /**
+     * Select Activations that may be evicted right now.
+     *
+     * An Activation is evictable only when nothing is owed: no in-flight task and
+     * no recent touch. A context over the resident ceiling is evicted by least
+     * recent touch — but a busy context is NEVER evicted to make room, because
+     * dropping work a peer is waiting on is worse than exceeding a soft ceiling.
+     * @returns Activations the caller should dispose and remove.
+     */
+    evictable(): Activation[];
+}
+//# sourceMappingURL=contexts.d.ts.map

package/lib/contexts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contexts.d.ts","sourceRoot":"","sources":["../src/contexts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAClE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAE1C,8BAA8B;AAC9B,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAA;IAChC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,mEAAmE;IACnE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,gFAAgF;IAChF,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAA;IACxC,mEAAmE;IACnE,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,0DAA0D;AAC1D,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,WAAW,CAAA;AAEnD,8DAA8D;AAC9D,qBAAa,eAAe;IASxB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,GAAG;IAVtB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsC;IAElE;;;;OAIG;gBAEgB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,GAAG,GAAE,MAAM,MAAiB;IAG/C,qDAAqD;IACrD,MAAM,IAAI,UAAU,EAAE;IAItB,gDAAgD;IAChD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,SAAS,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,aAAa;IAQzE;;;OAGG;IACH,GAAG,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI;IAIjC;;;;OAIG;IACH,MAAM,CAAC,SAAS,EAAE,YAAY,GAAG,UAAU,GAAG,SAAS;IAMvD,yEAAyE;IACzE,KAAK,IAAI,UAAU,EAAE;IAMrB;;;;;;;;OAQG;IACH,SAAS,IAAI,UAAU,EAAE;CAa1B"}

package/lib/contexts.js

@@ -0,0 +1,103 @@
+/**
+ * The contextId → Activation registry and its residency policy.
+ *
+ * This is the biggest structural difference from `dsh-acp`. ACP has a stdio
+ * connection whose lifetime owns its sessions; HTTP has no connection lifetime
+ * at all, so residency must be an explicit policy. An **Activation** is one
+ * residency epoch for a contextId — the same word `ctx.subagents` uses for a
+ * continuable child's residency, and the same shape: evicting an Activation
+ * releases the AgentHandle while the durable Session stays, so the next message
+ * cold-resumes rather than starting over.
+ *
+ * @module dsh-a2a/contexts
+ */
+/** Registry of resident contexts with LRU + idle eviction. */
+export class ContextRegistry {
+    maxResident;
+    idleTtlMs;
+    now;
+    activations = new Map();
+    /**
+     * @param maxResident - hard ceiling on resident contexts.
+     * @param idleTtlMs - how long an untouched, quiet context stays resident.
+     * @param now - clock injection point for tests.
+     */
+    constructor(maxResident, idleTtlMs, now = Date.now) {
+        this.maxResident = maxResident;
+        this.idleTtlMs = idleTtlMs;
+        this.now = now;
+    }
+    /** Every resident Activation, in insertion order. */
+    values() {
+        return [...this.activations.values()];
+    }
+    /** How many contexts are currently resident. */
+    get size() {
+        return this.activations.size;
+    }
+    /**
+     * Look up a context on behalf of an authenticated peer.
+     *
+     * A context owned by ANOTHER peer reports `forbidden`, and the caller must
+     * answer exactly as it answers `unknown` — otherwise a peer could enumerate
+     * which context ids exist by comparing the two responses.
+     * @param contextId - the id the peer presented.
+     * @param peer - the authenticated identity making the request.
+     * @returns the Activation, or why it is unavailable.
+     */
+    lookup(contextId, peer) {
+        const activation = this.activations.get(contextId);
+        if (activation === undefined)
+            return 'unknown';
+        if (activation.peer !== peer)
+            return 'forbidden';
+        activation.lastTouchedAt = this.now();
+        return activation;
+    }
+    /**
+     * Register a freshly created or resumed Activation.
+     * @param activation - the Activation to hold.
+     */
+    add(activation) {
+        this.activations.set(activation.contextId, activation);
+    }
+    /**
+     * Remove an Activation from the registry without disposing it.
+     * @param contextId - the context to forget.
+     * @returns the removed Activation, if it was resident.
+     */
+    remove(contextId) {
+        const activation = this.activations.get(contextId);
+        this.activations.delete(contextId);
+        return activation;
+    }
+    /** Forget every Activation and return them for the caller to dispose. */
+    drain() {
+        const all = this.values();
+        this.activations.clear();
+        return all;
+    }
+    /**
+     * Select Activations that may be evicted right now.
+     *
+     * An Activation is evictable only when nothing is owed: no in-flight task and
+     * no recent touch. A context over the resident ceiling is evicted by least
+     * recent touch — but a busy context is NEVER evicted to make room, because
+     * dropping work a peer is waiting on is worse than exceeding a soft ceiling.
+     * @returns Activations the caller should dispose and remove.
+     */
+    evictable() {
+        const cutoff = this.now() - this.idleTtlMs;
+        const quiet = this.values().filter(a => a.slots.size === 0);
+        const expired = quiet.filter(a => a.lastTouchedAt <= cutoff);
+        if (this.activations.size <= this.maxResident)
+            return expired;
+        const overflow = this.activations.size - this.maxResident;
+        const byOldest = quiet
+            .filter(a => !expired.includes(a))
+            .sort((a, b) => a.lastTouchedAt - b.lastTouchedAt)
+            .slice(0, Math.max(0, overflow - expired.length));
+        return [...expired, ...byOldest];
+    }
+}
+//# sourceMappingURL=contexts.js.map

package/lib/contexts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contexts.js","sourceRoot":"","sources":["../src/contexts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAwBH,8DAA8D;AAC9D,MAAM,OAAO,eAAe;IASP;IACA;IACA;IAVF,WAAW,GAAG,IAAI,GAAG,EAA4B,CAAA;IAElE;;;;OAIG;IACH,YACmB,WAAmB,EACnB,SAAiB,EACjB,MAAoB,IAAI,CAAC,GAAG;QAF5B,gBAAW,GAAX,WAAW,CAAQ;QACnB,cAAS,GAAT,SAAS,CAAQ;QACjB,QAAG,GAAH,GAAG,CAAyB;IAC5C,CAAC;IAEJ,qDAAqD;IACrD,MAAM;QACJ,OAAO,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,CAAA;IACvC,CAAC;IAED,gDAAgD;IAChD,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAA;IAC9B,CAAC;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,SAAuB,EAAE,IAAY;QAC1C,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;QAClD,IAAI,UAAU,KAAK,SAAS;YAAE,OAAO,SAAS,CAAA;QAC9C,IAAI,UAAU,CAAC,IAAI,KAAK,IAAI;YAAE,OAAO,WAAW,CAAA;QAChD,UAAU,CAAC,aAAa,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QACrC,OAAO,UAAU,CAAA;IACnB,CAAC;IAED;;;OAGG;IACH,GAAG,CAAC,UAAsB;QACxB,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,SAAS,EAAE,UAAU,CAAC,CAAA;IACxD,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,SAAuB;QAC5B,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;QAClD,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;QAClC,OAAO,UAAU,CAAA;IACnB,CAAC;IAED,yEAAyE;IACzE,KAAK;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,CAAA;QACzB,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAA;QACxB,OAAO,GAAG,CAAA;IACZ,CAAC;IAED;;;;;;;;OAQG;IACH,SAAS;QACP,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,CAAA;QAC1C,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,CAAC,CAAA;QAC3D,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,aAAa,IAAI,MAAM,CAAC,CAAA;QAC5D,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,IAAI,IAAI,CAAC,WAAW;YAAE,OAAO,OAAO,CAAA;QAE7D,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,GAAG,IAAI,CAAC,WAAW,CAAA;QACzD,MAAM,QAAQ,GAAG,KAAK;aACnB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;aACjC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,GAAG,CAAC,CAAC,aAAa,CAAC;aACjD,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAA;QACnD,OAAO,CAAC,GAAG,OAAO,EAAE,GAAG,QAAQ,CAAC,CAAA;IAClC,CAAC;CACF"}

package/lib/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Inbound A2A protocol server for DeepSeek Harness.
+ *
+ * Publishes an Agent Card at a well-known URI and serves the A2A v0.3.0
+ * JSON-RPC binding, so any compliant peer that knows this deployment's URL can
+ * discover it and submit tasks to a harness agent. There is no outbound client:
+ * this plugin never connects to another agent.
+ *
+ * It is a TRANSPORT ADAPTER, not a capability seam — the same self-limitation
+ * `dsh-acp` states. It exposes no editor navigation, transcript replay,
+ * commands, modes, or tool presentation.
+ *
+ * @module dsh-a2a-server
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { Config, type A2AServerConfig } from './config.ts';
+export { Config };
+export type { A2AServerConfig };
+export declare const name = "a2a-server";
+/**
+ * The server creates and owns agents, needs an HTTP carrier for its routes, and
+ * cannot authenticate a single request without the credential seam. Everything
+ * else it uses is probed with `ctx.get()` so a composition missing an optional
+ * capability still boots with A2A serving.
+ */
+export declare const inject: string[];
+/**
+ * Mount the inbound A2A server.
+ * @param ctx - the Cordis context carrying the agent factory, HTTP carrier, and credentials.
+ * @param config - the validated plugin configuration.
+ */
+export declare function apply(ctx: Context, config: A2AServerConfig): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAalD,OAAO,EAAwB,MAAM,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAA;AAchF,OAAO,EAAE,MAAM,EAAE,CAAA;AACjB,YAAY,EAAE,eAAe,EAAE,CAAA;AAE/B,eAAO,MAAM,IAAI,eAAe,CAAA;AAEhC;;;;;GAKG;AACH,eAAO,MAAM,MAAM,UAAyC,CAAA;AAW5D;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CAyejE"}