@aeolus-fleet/gateway 0.0.0-stage → 0.28.0

package/dist/core/mcp-in/ports.d.ts

@@ -0,0 +1,108 @@
+import type { DeliveryId, FleetId, MessageId, ShipId, ShipKind } from '@aeolus-fleet/common';
+import type { FleetRefusal } from '../connection/ports.js';
+import type { Result } from '../shared/result.js';
+import type { CallReply, ClientCall } from './client-call.js';
+/** One thing a ship offers, as its statement says it (decision 0047): MCP's tool fields and A2A's modes. */
+export interface Capability {
+    name: string;
+    title?: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    /** The media types to send it, the first the one to use. */
+    inputModes?: string[];
+    /** The media types that come back, the first the one to expect. */
+    outputModes?: string[];
+    /** How long a call waits for its answer before the caller is answered a handle or task; none is no wait (interop 5.3). */
+    waitMs?: number;
+    /** How long a call may take before it fails; none is no deadline (interop 3.4). */
+    deadlineMs?: number;
+}
+/** A ship's statement as discovery shows it: its crew's, the note it was commissioned with, or none. */
+export type DiscoveredStatement = {
+    by: 'crew';
+    summary: string;
+    capabilities: Capability[];
+} | {
+    by: 'commission';
+} | null;
+/** A ship the caller may send to now, as discover answers it. */
+export interface DiscoveredShip {
+    shipId: ShipId;
+    kind: ShipKind;
+    statement: DiscoveredStatement;
+}
+/** Outbound port: the fleet's discover, as a proxy ship's crew calls it. */
+export interface Discovery {
+    discover(crewToken: string): Promise<Result<DiscoveredShip[], FleetRefusal>>;
+}
+/**
+ * Outbound port: the name an outside client knows a ship by. Derived, never
+ * stored, the same for the same ship, and telling nothing of the ship's name
+ * or id: the gateway translates both ways, as NAT does.
+ */
+export interface ShipAliases {
+    aliasOf(fleetId: FleetId, shipId: ShipId): string;
+}
+/** Outbound port: the fleet's send, as a proxy ship's crew calls it. The same idempotency key answers the same message. */
+export interface CallSender {
+    send(crewToken: string, message: {
+        to: ShipId;
+        contentType: string;
+        payload: string;
+        idempotencyKey: string;
+    }): Promise<Result<{
+        messageId: MessageId;
+    }, FleetRefusal>>;
+}
+/**
+ * Outbound port: the keys of an outside client's call, derived under the
+ * gateway's own key. The outside sees only opaque ids, never a `msg_` id.
+ */
+export interface CallKeys {
+    /** The send's key for a client's own idempotency key: the same for the same party and key. */
+    idempotencyKeyOf(given: {
+        fleetId: FleetId;
+        party: string;
+        key: string;
+    }): string;
+    /** A new send key, for a call the client gave none. */
+    newIdempotencyKey(): string;
+    /** The handle the client reads its call by. */
+    handleOf(fleetId: FleetId, messageId: MessageId): string;
+}
+/** Outbound port: outside clients' calls, one per message, each with the replies naming it. */
+export interface ClientCalls {
+    /** Keeps a call with no replies; a call kept for its message already stays as it was. */
+    save(call: Omit<ClientCall, 'replies'>): Promise<void>;
+    /** Keeps a reply on the call its message names, once per delivery. */
+    addReply(call: {
+        fleetId: FleetId;
+        messageId: MessageId;
+    }, reply: CallReply): Promise<void>;
+    findByMessage(fleetId: FleetId, messageId: MessageId): Promise<ClientCall | undefined>;
+    /** The party's calls whose deadline has not passed by now, or that have none: those whose answer may still come. */
+    waitedOn(caller: {
+        fleetId: FleetId;
+        party: string;
+    }, now: Date): Promise<ClientCall[]>;
+    /** The party's call by its handle; none of another party's. */
+    findByHandle(caller: {
+        fleetId: FleetId;
+        party: string;
+    }, handle: string): Promise<ClientCall | undefined>;
+}
+/** A reply the fleet hands a proxy ship's crew: its delivery and its message. */
+export interface ReceivedReply {
+    deliveryId: DeliveryId;
+    messageId: MessageId;
+    contentType: string;
+    payload: string;
+}
+/** Outbound port: the fleet's receiveReply, as a proxy ship's crew calls it: the reply to one message, if one came within the fleet's wait. */
+export interface ReplyReceiver {
+    receiveReply(crewToken: string, wait: {
+        messageId: MessageId;
+        signal: AbortSignal;
+    }): Promise<Result<ReceivedReply | undefined, FleetRefusal>>;
+}

package/dist/core/mcp-in/ports.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ports.js.map

package/dist/core/mcp-in/ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.js","sourceRoot":"","sources":["../../../src/core/mcp-in/ports.ts"],"names":[],"mappings":""}

package/dist/core/mcp-in/read-client-call.d.ts

@@ -0,0 +1,23 @@
+import type { FleetId } from '@aeolus-fleet/common';
+import type { Clock } from '../shared/clock.js';
+import { type DomainError } from '../shared/errors.js';
+import { type Result } from '../shared/result.js';
+import { type CallState, type ClientCall } from './client-call.js';
+import type { ClientCalls } from './ports.js';
+/** A call as its client reads it (interop 3.4): its handle, when it was sent, its state and since when, with its answer once completed. */
+export type ReadCall = {
+    handle: string;
+    createdAt: Date;
+    updatedAt: Date;
+} & CallState;
+/** The call as its client reads it now. */
+export declare function readCallOf(call: ClientCall, now: Date): ReadCall;
+export type ReadClientCall = (caller: {
+    fleetId: FleetId;
+    party: string;
+}, handle: string) => Promise<Result<ReadCall, DomainError<'NO_SUCH_CALL'>>>;
+/** Use case: an outside client reads its own call by the handle it was answered; no other party's. */
+export declare function createReadClientCall(deps: {
+    calls: ClientCalls;
+    clock: Clock;
+}): ReadClientCall;

package/dist/core/mcp-in/read-client-call.js

@@ -0,0 +1,15 @@
+import { refuse } from '../shared/errors.js';
+import { ok } from '../shared/result.js';
+import { stateOf, stateSince } from './client-call.js';
+/** The call as its client reads it now. */
+export function readCallOf(call, now) {
+    return { handle: call.handle, createdAt: call.sentAt, updatedAt: stateSince(call, now), ...stateOf(call, now) };
+}
+/** Use case: an outside client reads its own call by the handle it was answered; no other party's. */
+export function createReadClientCall(deps) {
+    return async ({ fleetId, party }, handle) => {
+        const call = await deps.calls.findByHandle({ fleetId, party }, handle);
+        return call ? ok(readCallOf(call, deps.clock.now())) : refuse('NO_SUCH_CALL', 'This party made no call with that handle');
+    };
+}
+//# sourceMappingURL=read-client-call.js.map

package/dist/core/mcp-in/read-client-call.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-client-call.js","sourceRoot":"","sources":["../../../src/core/mcp-in/read-client-call.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,EAAoB,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,EAAE,EAAe,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,OAAO,EAAE,UAAU,EAAmC,MAAM,kBAAkB,CAAC;AAMxF,2CAA2C;AAC3C,MAAM,UAAU,UAAU,CAAC,IAAgB,EAAE,GAAS;IACpD,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;AAClH,CAAC;AAID,sGAAsG;AACtG,MAAM,UAAU,oBAAoB,CAAC,IAA0C;IAC7E,OAAO,KAAK,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,EAAE;QAC1C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,MAAM,CAAC,CAAC;QACvE,OAAO,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,cAAc,EAAE,0CAA0C,CAAC,CAAC;IAC5H,CAAC,CAAC;AACJ,CAAC"}

package/dist/core/mcp-out/content-types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The content types that carry an outside tool's call and its result over
+ * the fleet (orchestrator-1 on aeolus-fleet#876, Q7): the input type names
+ * the tool, and its payload is the tool's arguments as a JSON object; the
+ * result type names the tool too, and its payload is the tool's result.
+ */
+export declare function toolInputType(tool: string): string;
+export declare function toolResultType(tool: string): string;
+/** The tool a message of this content type calls; none for another type, or the input type without a name. */
+export declare function toolCalledBy(contentType: string): string | undefined;
+/** Whether a message of this content type carries a tool's result. */
+export declare function isToolResultType(contentType: string): boolean;

package/dist/core/mcp-out/content-types.js

@@ -0,0 +1,28 @@
+/**
+ * The content types that carry an outside tool's call and its result over
+ * the fleet (orchestrator-1 on aeolus-fleet#876, Q7): the input type names
+ * the tool, and its payload is the tool's arguments as a JSON object; the
+ * result type names the tool too, and its payload is the tool's result.
+ */
+const TOOL_INPUT = 'application/vnd.aeolus.mcp-tool+json';
+const TOOL_RESULT = 'application/vnd.aeolus.mcp-result+json';
+export function toolInputType(tool) {
+    return `${TOOL_INPUT}; name=${tool}`;
+}
+export function toolResultType(tool) {
+    return `${TOOL_RESULT}; name=${tool}`;
+}
+/** The tool a message of this content type calls; none for another type, or the input type without a name. */
+export function toolCalledBy(contentType) {
+    const [type, ...parameters] = contentType.split(';').map((part) => part.trim());
+    if (type?.toLowerCase() !== TOOL_INPUT) {
+        return undefined;
+    }
+    const name = parameters.find((parameter) => parameter.toLowerCase().startsWith('name='))?.slice('name='.length);
+    return name === undefined || name === '' ? undefined : name;
+}
+/** Whether a message of this content type carries a tool's result. */
+export function isToolResultType(contentType) {
+    return contentType.split(';')[0]?.trim().toLowerCase() === TOOL_RESULT;
+}
+//# sourceMappingURL=content-types.js.map

package/dist/core/mcp-out/content-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-types.js","sourceRoot":"","sources":["../../../src/core/mcp-out/content-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,UAAU,GAAG,sCAAsC,CAAC;AAC1D,MAAM,WAAW,GAAG,wCAAwC,CAAC;AAE7D,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,GAAG,UAAU,UAAU,IAAI,EAAE,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,GAAG,WAAW,UAAU,IAAI,EAAE,CAAC;AACxC,CAAC;AAED,8GAA8G;AAC9G,MAAM,UAAU,YAAY,CAAC,WAAmB;IAC9C,MAAM,CAAC,IAAI,EAAE,GAAG,UAAU,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAChF,IAAI,IAAI,EAAE,WAAW,EAAE,KAAK,UAAU,EAAE,CAAC;QACvC,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAChH,OAAO,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9D,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,gBAAgB,CAAC,WAAmB;IAClD,OAAO,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,WAAW,CAAC;AACzE,CAAC"}

package/dist/core/mcp-out/hand-call.d.ts

@@ -0,0 +1,105 @@
+import { type DeliveryId, type FleetId, type MessageId, type ShipId } from '@aeolus-fleet/common';
+import type { FleetRefusal } from '../connection/ports.js';
+import type { McpServerParty } from '../parties/party.js';
+import type { Result } from '../shared/result.js';
+import type { McpServers } from './ports.js';
+import type { ToolMarks } from './state-party.js';
+/** A delivery to a proxy ship, as its pushReceive hands it: received, or handed before under this lease with its last number. */
+export interface PushedDelivery {
+    readonly deliveryId: DeliveryId;
+    readonly messageId: MessageId;
+    readonly senderShipId: ShipId;
+    readonly contentType: string;
+    readonly payload: string;
+    readonly state: 'received' | 'handed';
+    readonly handOverNumber: number | null;
+    /** The message this one replies to, if any. */
+    readonly inReplyTo: MessageId | null;
+}
+/** A reply naming the request, sent as the proxy ship. */
+export interface Reply {
+    readonly to: ShipId;
+    readonly inReplyTo: MessageId;
+    readonly contentType: string;
+    readonly payload: string;
+    readonly idempotencyKey: string;
+}
+/** Outbound port: the fleet's calls a proxy ship's crew makes (decision 0040), each with its crew token. */
+export interface ProxyShipCrew {
+    /** Its deliveries, up to max: its own in flight first, then pending ones, each received; it waits a while for one, or less once the signal aborts. */
+    pushReceive(crewToken: string, take: {
+        max: number;
+        signal: AbortSignal;
+    }): Promise<Result<PushedDelivery[], FleetRefusal>>;
+    /** Hands the delivery over with its number, naming the channel it went through (interop 5.1). */
+    handed(crewToken: string, handOver: {
+        deliveryId: DeliveryId;
+        handOverNumber: number;
+        channel: string;
+    }): Promise<Result<'handed' | 'acknowledged' | 'undeliverable', FleetRefusal>>;
+    reply(crewToken: string, reply: Reply): Promise<Result<void, FleetRefusal>>;
+    ack(crewToken: string, deliveryId: DeliveryId): Promise<Result<void, FleetRefusal>>;
+    handled(crewToken: string, deliveryId: DeliveryId): Promise<Result<void, FleetRefusal>>;
+    notHandled(crewToken: string, report: {
+        deliveryId: DeliveryId;
+        reason: string;
+    }): Promise<Result<void, FleetRefusal>>;
+}
+/**
+ * What the gateway keeps of a call, so a restart never calls again what may have run:
+ * - calling: handed, and its `tools/call` sent or about to be;
+ * - notSent: the server was not reached, so nothing ran;
+ * - answered: the server answered, and its reply is kept until it is sent;
+ * - mayHaveRun: sent with no answer, and its tool is not marked repeatable;
+ * - done: replied, acknowledged and handled.
+ */
+export interface Call {
+    readonly deliveryId: DeliveryId;
+    readonly fleetId: FleetId;
+    readonly party: string;
+    readonly state: 'calling' | 'notSent' | 'answered' | 'mayHaveRun' | 'done';
+    readonly reply: Reply | null;
+}
+/** Outbound port: the gateway's calls, by delivery. */
+export interface CallStore {
+    find(deliveryId: DeliveryId): Promise<Call | undefined>;
+    save(call: Call): Promise<void>;
+}
+/**
+ * How handing one delivery ended:
+ * - handled: replied, acknowledged and handled;
+ * - again: nothing ran, or running it again is safe: the delivery comes again in flight, to be handed with the next number;
+ * - notHandled: the call may have run and its answer was lost, so a human decides (5.2, option a);
+ * - undeliverable: the fifth attempt; nothing is handed.
+ */
+export type HandOutcome = {
+    readonly kind: 'handled';
+} | {
+    readonly kind: 'again';
+} | {
+    readonly kind: 'notHandled';
+} | {
+    readonly kind: 'undeliverable';
+};
+export type HandCall = (input: {
+    party: McpServerParty;
+    delivery: PushedDelivery;
+}) => Promise<HandOutcome>;
+/** The reason a call that may have run is not handled, as Needs attention shows it. */
+export declare const MAY_HAVE_RUN = "The call may have run; its answer was lost. Check the outside system, then resend or dismiss.";
+/**
+ * Use case: the gateway hands one delivery of a party's proxy ship to its
+ * outside MCP server, as 0040 hands one to an agent (interop 5.2): handed
+ * with the next number, then `tools/call`; the server's answer confirms it,
+ * so it is replied, acknowledged and handled at once. The answer is kept
+ * before the reply, so a restart replies again under the same key and calls
+ * nothing. A call that died unanswered is handed again only where argo
+ * marked its tool repeatable; otherwise it is reported not handled.
+ */
+export declare function createHandCall(deps: {
+    crew: ProxyShipCrew;
+    servers: McpServers;
+    calls: CallStore;
+    marks: ToolMarks;
+    timeoutMs: number;
+}): HandCall;

package/dist/core/mcp-out/hand-call.js

@@ -0,0 +1,118 @@
+import { PAYLOAD_MAX_BYTES, payloadBytes } from '@aeolus-fleet/common';
+import { toolCalledBy, toolInputType, toolResultType } from './content-types.js';
+/** The channel the gateway hands a proxy ship's delivery through: its outside MCP server (interop 5.1). */
+const MCP_CHANNEL = 'mcp';
+/** The reason a call that may have run is not handled, as Needs attention shows it. */
+export const MAY_HAVE_RUN = 'The call may have run; its answer was lost. Check the outside system, then resend or dismiss.';
+const AGAIN = { kind: 'again' };
+function isArguments(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function argumentsOf(payload) {
+    try {
+        const parsed = JSON.parse(payload);
+        return isArguments(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function errorResult(text) {
+    return { content: [{ type: 'text', text }], isError: true };
+}
+/** The reply carrying a tool's result; one too large for a message is replaced by an error result that says so. */
+function resultReply(delivery, call) {
+    const payload = JSON.stringify(call.result);
+    const bytes = payloadBytes(payload);
+    return {
+        to: delivery.senderShipId,
+        inReplyTo: delivery.messageId,
+        contentType: toolResultType(call.tool),
+        payload: bytes > PAYLOAD_MAX_BYTES ? JSON.stringify(errorResult(`The tool result is ${String(bytes)} bytes as JSON, over the ${String(PAYLOAD_MAX_BYTES)} a message holds.`)) : payload,
+        idempotencyKey: `mcp-result:${delivery.messageId}`,
+    };
+}
+function notACallReply(party, delivery) {
+    return {
+        to: delivery.senderShipId,
+        inReplyTo: delivery.messageId,
+        contentType: 'text/plain',
+        payload: `${party.name} takes only tool calls: send a capability's input type, ${toolInputType('<tool>')}, with the tool arguments as a JSON object.`,
+        idempotencyKey: `mcp-result:${delivery.messageId}`,
+    };
+}
+/**
+ * Use case: the gateway hands one delivery of a party's proxy ship to its
+ * outside MCP server, as 0040 hands one to an agent (interop 5.2): handed
+ * with the next number, then `tools/call`; the server's answer confirms it,
+ * so it is replied, acknowledged and handled at once. The answer is kept
+ * before the reply, so a restart replies again under the same key and calls
+ * nothing. A call that died unanswered is handed again only where argo
+ * marked its tool repeatable; otherwise it is reported not handled.
+ */
+export function createHandCall(deps) {
+    return async ({ party, delivery }) => {
+        const crewToken = party.crewToken;
+        if (crewToken === null) {
+            return AGAIN;
+        }
+        const kept = { deliveryId: delivery.deliveryId, fleetId: party.fleetId, party: party.name };
+        const finish = async (reply) => {
+            for (const step of [() => deps.crew.reply(crewToken, reply), () => deps.crew.ack(crewToken, delivery.deliveryId), () => deps.crew.handled(crewToken, delivery.deliveryId)]) {
+                if (!(await step()).isOk) {
+                    return AGAIN;
+                }
+            }
+            await deps.calls.save({ ...kept, state: 'done', reply });
+            return { kind: 'handled' };
+        };
+        const mayHaveRun = async () => {
+            await deps.calls.save({ ...kept, state: 'mayHaveRun', reply: null });
+            // A refused report leaves the call judged: it is reported again each time it comes, and never called again.
+            await deps.crew.notHandled(crewToken, { deliveryId: delivery.deliveryId, reason: MAY_HAVE_RUN });
+            return { kind: 'notHandled' };
+        };
+        const call = await deps.calls.find(delivery.deliveryId);
+        if (call?.state === 'mayHaveRun') {
+            return mayHaveRun();
+        }
+        if (call?.reply) {
+            return finish(call.reply);
+        }
+        const tool = toolCalledBy(delivery.contentType);
+        if (tool === undefined) {
+            return finish(notACallReply(party, delivery));
+        }
+        const args = argumentsOf(delivery.payload);
+        if (args === undefined) {
+            return finish(resultReply(delivery, { tool, result: errorResult('The tool arguments must be a JSON object.') }));
+        }
+        const isRepeatable = (await deps.marks.repeatable(party.fleetId, party.name)).has(tool);
+        // Handed before with no answer kept and not judged unsent: the gateway stopped mid call, so it may have run.
+        if (delivery.state === 'handed' && call?.state !== 'notSent' && !isRepeatable) {
+            return mayHaveRun();
+        }
+        const handed = await deps.crew.handed(crewToken, { deliveryId: delivery.deliveryId, handOverNumber: (delivery.handOverNumber ?? 0) + 1, channel: MCP_CHANNEL });
+        if (!handed.isOk) {
+            return AGAIN;
+        }
+        if (handed.value === 'undeliverable') {
+            return { kind: 'undeliverable' };
+        }
+        await deps.calls.save({ ...kept, state: 'calling', reply: null });
+        const outcome = await deps.servers.callTool({ url: party.url, credential: party.credential }, { name: tool, arguments: args, timeoutMs: deps.timeoutMs });
+        switch (outcome.kind) {
+            case 'answered': {
+                const reply = resultReply(delivery, { tool, result: outcome.result });
+                await deps.calls.save({ ...kept, state: 'answered', reply });
+                return finish(reply);
+            }
+            case 'notSent':
+                await deps.calls.save({ ...kept, state: 'notSent', reply: null });
+                return AGAIN;
+            case 'unanswered':
+                return isRepeatable ? AGAIN : mayHaveRun();
+        }
+    };
+}
+//# sourceMappingURL=hand-call.js.map

package/dist/core/mcp-out/hand-call.js.map

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

package/dist/core/mcp-out/mark-tool.d.ts

@@ -0,0 +1,20 @@
+import type { FleetId } from '@aeolus-fleet/common';
+import type { PartyStore } from '../parties/ports.js';
+import type { StateParty, ToolMarks } from './state-party.js';
+export type MarkTool = (input: {
+    fleetId: FleetId;
+    name: string;
+    tool: string;
+    isRepeatable: boolean;
+}) => ReturnType<StateParty>;
+/**
+ * Use case: argo marks a party's tool repeatable, or takes the mark off
+ * (interop 5.2): a call to it that died unanswered may then be handed
+ * again. The mark is kept first and stated at once; while the statement
+ * cannot be made, the mark waits for the next.
+ */
+export declare function createMarkTool(deps: {
+    parties: PartyStore;
+    marks: ToolMarks;
+    stateParty: StateParty;
+}): MarkTool;

package/dist/core/mcp-out/mark-tool.js

@@ -0,0 +1,17 @@
+import { refuse } from '../shared/errors.js';
+/**
+ * Use case: argo marks a party's tool repeatable, or takes the mark off
+ * (interop 5.2): a call to it that died unanswered may then be handed
+ * again. The mark is kept first and stated at once; while the statement
+ * cannot be made, the mark waits for the next.
+ */
+export function createMarkTool(deps) {
+    return async ({ fleetId, name, tool, isRepeatable }) => {
+        if (!(await deps.parties.find(fleetId, name))) {
+            return refuse('NO_SUCH_PARTY', `No party named ${name}`);
+        }
+        await deps.marks.mark(fleetId, { party: name, tool, isRepeatable });
+        return deps.stateParty({ fleetId, name });
+    };
+}
+//# sourceMappingURL=mark-tool.js.map

package/dist/core/mcp-out/mark-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mark-tool.js","sourceRoot":"","sources":["../../../src/core/mcp-out/mark-tool.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAK7C;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,IAAuE;IACpG,OAAO,KAAK,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE;QACrD,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC;YAC9C,OAAO,MAAM,CAAC,eAAe,EAAE,kBAAkB,IAAI,EAAE,CAAC,CAAC;QAC3D,CAAC;QACD,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC;QACpE,OAAO,IAAI,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5C,CAAC,CAAC;AACJ,CAAC"}

package/dist/core/mcp-out/ports.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The outside MCP server behind an app proxy ship, as MCP out sees it
+ * (interop 3.3, 5.2): its tools, and one call at a time.
+ */
+import type { Result } from '../shared/result.js';
+import type { McpServerCredential } from '../vault/credential.js';
+/** Where an outside MCP server is, and how the gateway signs in to it. */
+export interface McpServerConnection {
+    /** Its Streamable HTTP endpoint. */
+    readonly url: string;
+    readonly credential: McpServerCredential;
+}
+/** MCP's tool annotations (2026-07-28), as the server states them: hints, never trusted on their own. */
+export interface ToolAnnotations {
+    readonly title?: string;
+    readonly readOnlyHint?: boolean;
+    readonly destructiveHint?: boolean;
+    readonly idempotentHint?: boolean;
+    readonly openWorldHint?: boolean;
+}
+/** One tool of an outside MCP server, as its `tools/list` answers it. */
+export interface OutsideTool {
+    readonly name: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly inputSchema: Readonly<Record<string, unknown>>;
+    readonly outputSchema?: Readonly<Record<string, unknown>>;
+    readonly annotations?: ToolAnnotations;
+}
+/** A tool's answer: its result, an error result included (`isError`). */
+export interface ToolResult {
+    readonly content: readonly unknown[];
+    readonly structuredContent?: Readonly<Record<string, unknown>>;
+    readonly isError: boolean;
+}
+/**
+ * How one `tools/call` ended (5.2):
+ * - answered: the server's answer, which confirms the hand-over;
+ * - notSent: the gateway never sent it (the server was unreachable, or refused the gateway's credential), so it did not run;
+ * - unanswered: sent, and no answer came (a broken stream, a timeout): whether the server ran it is unknown.
+ */
+export type ToolCallOutcome = {
+    readonly kind: 'answered';
+    readonly result: ToolResult;
+} | {
+    readonly kind: 'notSent';
+    readonly reason: string;
+} | {
+    readonly kind: 'unanswered';
+    readonly reason: string;
+};
+export interface ToolCall {
+    readonly name: string;
+    readonly arguments: Readonly<Record<string, unknown>>;
+    /** How long the gateway waits for the answer before it counts the call as unanswered. */
+    readonly timeoutMs: number;
+}
+/** The outside MCP servers the gateway calls. */
+export interface McpServers {
+    /** The server's tools, every page of them; unreachable when it cannot be listed. */
+    listTools(connection: McpServerConnection): Promise<Result<readonly OutsideTool[], {
+        readonly kind: 'unreachable';
+        readonly reason: string;
+    }>>;
+    callTool(connection: McpServerConnection, call: ToolCall): Promise<ToolCallOutcome>;
+}

package/dist/core/mcp-out/ports.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ports.js.map

package/dist/core/mcp-out/ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.js","sourceRoot":"","sources":["../../../src/core/mcp-out/ports.ts"],"names":[],"mappings":""}

package/dist/core/mcp-out/run-party.d.ts

@@ -0,0 +1,26 @@
+import type { McpServerParty } from '../parties/party.js';
+import type { HandCall, ProxyShipCrew } from './hand-call.js';
+/** Outbound port: waits the given time, or less once the signal aborts. */
+export type Sleep = (ms: number, signal: AbortSignal) => Promise<void>;
+export type RunParty = (input: {
+    party: McpServerParty;
+    signal: AbortSignal;
+}) => Promise<{
+    ended: 'stopped' | 'crewRefused';
+}>;
+/**
+ * Use case: the gateway takes the calls of a party's proxy ship, as its
+ * crew, until it is stopped (interop 5.2). Each delivery pushReceive takes
+ * is handed to the server once while in flight, with no more calls at once
+ * than the party takes. A delivery answered again waits, longer each time,
+ * before it is handed with the next number; the fleet counts each an
+ * attempt and stops at the fifth. While the fleet answers only what the
+ * gateway already holds, or does not answer, it looks again after a while.
+ */
+export declare function createRunParty(deps: {
+    crew: ProxyShipCrew;
+    handCall: HandCall;
+    sleep: Sleep;
+    pollMs: number;
+    againWaitsMs: readonly number[];
+}): RunParty;

package/dist/core/mcp-out/run-party.js

@@ -0,0 +1,62 @@
+/** The fleet's codes for a crew token it no longer takes: the gateway does not crew the proxy ship any more. */
+const CREW_REFUSED = new Set(['UNAUTHORIZED', 'LEASE_ENDED']);
+/**
+ * Use case: the gateway takes the calls of a party's proxy ship, as its
+ * crew, until it is stopped (interop 5.2). Each delivery pushReceive takes
+ * is handed to the server once while in flight, with no more calls at once
+ * than the party takes. A delivery answered again waits, longer each time,
+ * before it is handed with the next number; the fleet counts each an
+ * attempt and stops at the fifth. While the fleet answers only what the
+ * gateway already holds, or does not answer, it looks again after a while.
+ */
+export function createRunParty(deps) {
+    return async ({ party, signal }) => {
+        const crewToken = party.crewToken;
+        if (crewToken === null) {
+            return { ended: 'crewRefused' };
+        }
+        const max = party.concurrencyLimit;
+        const inFlight = new Map();
+        const agains = new Map();
+        const hand = async (delivery) => {
+            let outcome;
+            try {
+                outcome = await deps.handCall({ party, delivery });
+            }
+            catch {
+                // A failure of the gateway's own (its database): nothing was decided, so the delivery comes again.
+                outcome = { kind: 'again' };
+            }
+            if (outcome.kind === 'again') {
+                const count = (agains.get(delivery.deliveryId) ?? 0) + 1;
+                agains.set(delivery.deliveryId, count);
+                await deps.sleep(deps.againWaitsMs[Math.min(count, deps.againWaitsMs.length) - 1] ?? deps.pollMs, signal);
+            }
+            else {
+                agains.delete(delivery.deliveryId);
+            }
+        };
+        const start = (delivery) => {
+            inFlight.set(delivery.deliveryId, hand(delivery).finally(() => inFlight.delete(delivery.deliveryId)));
+        };
+        while (!signal.aborted) {
+            if (inFlight.size >= max) {
+                await Promise.race(inFlight.values());
+                continue;
+            }
+            const received = await deps.crew.pushReceive(crewToken, { max, signal });
+            if (!received.isOk && CREW_REFUSED.has(received.error.code)) {
+                await Promise.all(inFlight.values());
+                return { ended: 'crewRefused' };
+            }
+            const fresh = received.isOk ? received.value.filter((delivery) => !inFlight.has(delivery.deliveryId)).slice(0, max - inFlight.size) : [];
+            fresh.forEach(start);
+            if (fresh.length === 0) {
+                await Promise.race([deps.sleep(deps.pollMs, signal), ...inFlight.values()]);
+            }
+        }
+        await Promise.all(inFlight.values());
+        return { ended: 'stopped' };
+    };
+}
+//# sourceMappingURL=run-party.js.map