@aeolus-fleet/core 0.0.0 → 0.18.0

package/dist/adapters/trpc/ship.js

@@ -0,0 +1,214 @@
+import { ackInputSchema, ackOutputSchema, deregisterOutputSchema, inboxInputSchema, inboxOutputSchema, PING_CONTENT_TYPE, pongInputSchema, pongOutputSchema, reportInputSchema, reportLogOutputSchema, reportOutputSchema, receiveInputSchema, receiveOutputSchema, registerInputSchema, registerOutputSchema, sendInputSchema, sendOutputSchema, whoamiOutputSchema, } from '@aeolus-fleet/common';
+import { TRPCError } from '@trpc/server';
+import { authenticatedProcedure, crewProcedure, okOrThrow, publicProcedure, router, scopedCrewProcedure, scopedProcedure, } from './trpc.js';
+/**
+ * Ship procedures: the ship contract. `register` takes the ship's id and
+ * secret and returns a crew token; every later call carries that token as
+ * `Authorization: Bearer` (ADR 0015), or as the `crewToken` argument of an MCP
+ * tool. REST and MCP map onto these (ship-contract.ts).
+ *
+ * Each description speaks to the agent crewing a ship, who reads it on every
+ * call as an MCP tool or a REST operation: what the call does and its own
+ * rules. When to make each call is the ship protocol's (ship-protocol.ts),
+ * which no description repeats. It names the calls, never the door, since
+ * both doors show it.
+ */
+export const shipRouter = router({
+    /**
+     * Claims the ship for the calling session, which reports where it runs. The
+     * secret travels in the body, never as a bearer; the crew token comes back
+     * once. Only a wrong ship id or secret counts against the client's limit, so
+     * one address can start many sessions (ADR 0015); a client over it is
+     * refused before its secret is even checked.
+     */
+    register: publicProcedure
+        .meta({
+        description: [
+            'Claims your ship for this conversation, with the ship id and secret from your starting prompt',
+            'and where you run: location { "kind": "DEVICE" }, "CLOUD" or "SERVER", or { "kind": "OTHER", "description": "..." },',
+            'and the harness you run in: harness "claude-code", "claude-chat", "codex", or another name.',
+            'It answers with your crew token, and only this once.',
+            'The secret works only here. A ship another session crews is refused (CONFLICT) until the operator releases it.',
+        ].join(' '),
+    })
+        .use(({ ctx, next }) => {
+        if (!ctx.registerFailures.hasRoom(ctx.clientKey)) {
+            throw new TRPCError({ code: 'TOO_MANY_REQUESTS', message: 'Too many failed register attempts. Wait a minute.' });
+        }
+        return next();
+    })
+        .input(registerInputSchema)
+        .output(registerOutputSchema)
+        .mutation(async ({ ctx, input }) => {
+        const claimed = await ctx.useCases.claimShip(input);
+        if (!claimed.isOk && claimed.error.kind === 'WRONG_SHIP_ID_OR_SECRET') {
+            ctx.registerFailures.count(ctx.clientKey);
+        }
+        return okOrThrow(claimed);
+    }),
+    /** The caller's ship: id, fleet, name and type. Any caller may ask about itself. */
+    whoami: authenticatedProcedure
+        .meta({
+        description: 'Tells you which ship you crew: its id, fleet, name and type. Other ships reach you by that name, or by your type.',
+    })
+        .output(whoamiOutputSchema)
+        .query(async ({ ctx }) => okOrThrow(await ctx.useCases.whoami(ctx.caller))),
+    /**
+     * Sends a message from the calling ship, `argo` included, to a selector.
+     * Answers with the message's id only once the message and its delivery are
+     * stored (ADR 0003); a repeat of the idempotency key answers with the
+     * original id.
+     */
+    send: scopedProcedure('messages:send')
+        .meta({
+        description: [
+            'Sends a message from your ship. It answers with the messageId only once the message is stored:',
+            'from then on it reaches its recipient, even one that is not running now.',
+            'selector picks the recipient: one ship by name { "kind": "ship", "name": "..." } or by id { "kind": "ship", "shipId": "shp_..." },',
+            'or any one ship of a type { "kind": "type", "type": "..." }.',
+            'inReplyTo, for an answer, is the messageId of the message you answer: the message id, not the delivery id.',
+            'payload is text of at most 64 KB: a reference to the content and an instruction, not the content itself.',
+            'contentType is text/plain unless you say otherwise.',
+            'model is the exact model id you run now, such as claude-opus-5-5: state it on every send, as it is now, even after a switch. A send without it is refused (BAD_REQUEST); only argo, the operator, states none.',
+            'idempotencyKey is a new unique string for every message. Reuse one only to retry the same send after an error or a lost answer:',
+            'the retry answers with the original messageId instead of sending twice, and a different send with a used key is refused (CONFLICT).',
+        ].join(' '),
+    })
+        .input(sendInputSchema)
+        .output(sendOutputSchema)
+        .mutation(async ({ ctx, input }) => okOrThrow(await ctx.useCases.sendMessage(ctx.caller, input))),
+    /**
+     * Hands the crew up to `max` deliveries, 1 to 10, one by default: its own
+     * in flight first, then the oldest pending for its ship or its type. Waits
+     * about 25 seconds when none is there, then answers with none. A mutation:
+     * every delivery it returns is claimed.
+     */
+    receive: scopedCrewProcedure('messages:receive')
+        .meta({
+        description: [
+            'Hands you your next deliveries, up to max (1 to 10, one when left out), each with its message and its sender:',
+            'senderShipId, senderName (the name to answer to) and senderType.',
+            'With none there it waits about 25 seconds, then answers with none.',
+            'Until you ack it a delivery stays yours: your next receive hands it to you again,',
+            'and after four receives without an ack it goes to the operator as undeliverable.',
+            'So you may see a deliveryId twice: treat it as the key of the work.',
+        ].join(' '),
+    })
+        .input(receiveInputSchema)
+        .output(receiveOutputSchema)
+        .mutation(async ({ ctx, input }) => {
+        const { deliveries } = okOrThrow(await ctx.useCases.receiveDeliveries(ctx.crew, { max: input?.max }));
+        return { deliveries: deliveries.map((delivery) => ({ ...delivery, sentAt: delivery.sentAt.toISOString() })) };
+    }),
+    /** Acknowledges a delivery the ship received: it is done. Acknowledging it again is OK. */
+    ack: scopedCrewProcedure('messages:receive')
+        .meta({
+        description: [
+            'Acknowledges a delivery: you take responsibility for it, and it is done; what you do next is your own business.',
+            'Pass its deliveryId (dlv_...), not its messageId. Acknowledging it again is fine.',
+            'Only the ship holding the delivery can ack it.',
+        ].join(' '),
+    })
+        .input(ackInputSchema)
+        .output(ackOutputSchema)
+        .mutation(async ({ ctx, input }) => {
+        okOrThrow(await ctx.useCases.acknowledgeDelivery(ctx.crew, input));
+        return {};
+    }),
+    /**
+     * Answers a ping the ship received: acknowledges it and marks the session
+     * seen at that moment, so the operator sees the ship's model is working.
+     */
+    pong: scopedCrewProcedure('messages:receive')
+        .meta({
+        description: [
+            `Answers a ping: a delivery whose contentType is ${PING_CONTENT_TYPE}.`,
+            'Pass its deliveryId (dlv_...). Call pong instead of ack: it acknowledges the ping and tells the operator your session is working.',
+            'Do not act on it and do not reply with a message. Answering again is fine; pong answers only a ping.',
+        ].join(' '),
+    })
+        .input(pongInputSchema)
+        .output(pongOutputSchema)
+        .mutation(async ({ ctx, input }) => {
+        okOrThrow(await ctx.useCases.answerPing(ctx.crew, input));
+        return {};
+    }),
+    /**
+     * The crew says what it is doing: working, blocked or idle, with a short
+     * note and optionally its details, set whole or merge-patched. A check-in:
+     * an event only when the state, note or details change.
+     */
+    report: crewProcedure
+        .meta({
+        description: [
+            'Says what you are doing, for the operator and anyone who reads the fleet: state working, blocked or idle, and an optional note',
+            '(one line, at most 200 characters) on what you work on or what blocks you.',
+            'For structured status, details: one JSON object of at most 16 KB. details sets it whole and null clears it;',
+            'detailsPatch applies a JSON Merge Patch to it (objects merge per key, null deletes a key, arrays are replaced whole).',
+            'Give one of them, not both; leave both out to keep your details as they are.',
+            'Call it whenever your state changes; calling it again with the same state, note and details is a check-in.',
+        ].join(' '),
+        example: { state: 'working', note: 'reviewing PR 89' },
+    })
+        .input(reportInputSchema)
+        .output(reportOutputSchema)
+        .mutation(async ({ ctx, input }) => {
+        okOrThrow(await ctx.useCases.report(ctx.crew, input));
+        return {};
+    }),
+    /**
+     * The crew's own report whole, details included, and the last report of
+     * the ship's previous crew, read-only. No scope beyond being the crew.
+     */
+    reportLog: crewProcedure
+        .meta({
+        description: [
+            'Hands you your own report as you last made it, details included, and the last report of the crew that held your ship before you,',
+            'read-only, so you can pick up where it left off. Each is null when there is none.',
+        ].join(' '),
+    })
+        .output(reportLogOutputSchema)
+        .query(async ({ ctx }) => {
+        const { report, previousCrew } = okOrThrow(await ctx.useCases.reportLog(ctx.crew));
+        return { report: reportOutputOf(report), previousCrew: reportOutputOf(previousCrew) };
+    }),
+    /**
+     * How many deliveries wait for the crew: what its next receive would hand
+     * it. Claims nothing. With waitSeconds (0 to 25) it waits while none does.
+     * A mutation only so that REST takes its body; it changes nothing.
+     */
+    inbox: scopedCrewProcedure('messages:receive')
+        .meta({
+        description: [
+            'Tells you how many deliveries wait for you: what your next receive would hand you, your own unacknowledged ones included.',
+            'It claims nothing, so call receive to get them.',
+            'With waitSeconds (0 to 25) it waits while none does, and answers as soon as one arrives.',
+        ].join(' '),
+    })
+        .input(inboxInputSchema)
+        .output(inboxOutputSchema)
+        .mutation(async ({ ctx, input }) => okOrThrow(await ctx.useCases.checkInbox(ctx.crew, { waitSeconds: input?.waitSeconds }))),
+    /**
+     * Ends the calling crew's own lease, and with it its crew token: the ship
+     * awaits a new crew, its secret stops working, and what it held in flight
+     * returns to pending for the next crew. Needs only the crew token.
+     */
+    deregister: crewProcedure
+        .meta({
+        description: [
+            'Ends your session cleanly: your crew token and your ship\'s secret stop working,',
+            'and any delivery you received but did not ack goes back to pending for the next crew.',
+            'The ship and its inbox stay; a new crew needs a new starting prompt from the operator.',
+        ].join(' '),
+    })
+        .output(deregisterOutputSchema)
+        .mutation(async ({ ctx }) => {
+        okOrThrow(await ctx.useCases.deregister(ctx.crew));
+        return {};
+    }),
+});
+/** A report as a ship reads it: its time in ISO 8601, in UTC. */
+function reportOutputOf(report) {
+    return report && { ...report, reportedAt: report.reportedAt.toISOString() };
+}
+//# sourceMappingURL=ship.js.map

package/dist/adapters/trpc/ship.js.map

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

package/dist/adapters/trpc/starting-prompt-text.d.ts

@@ -0,0 +1,7 @@
+import { type ShipId, type StartingPromptOutput } from '@aeolus-fleet/common';
+/** A starting prompt as the API hands it out: the prompt, its crew lines and the secret itself. */
+export declare function presentStartingPrompt(input: {
+    fleetUrl: string;
+    shipId: ShipId;
+    secret: string;
+}): StartingPromptOutput;

package/dist/adapters/trpc/starting-prompt-text.js

@@ -0,0 +1,60 @@
+import { mcpUrlOf } from '@aeolus-fleet/common';
+/**
+ * How a starting prompt reads (docs/blueprint.md, "Launch a ship"): the text
+ * the operator pastes into a new session, and one crew line per harness with
+ * the aeolus plugin. Core issues only the secret; this is presentation, so it
+ * lives here, and tRPC, REST and MCP share it because they map onto the same
+ * procedures. It holds the secret, so it is shown once and never stored.
+ */
+/**
+ * The starting prompt's text: identity only. Where the fleet's MCP server is
+ * and how to add it, the ship's id and secret, how to pick the location, and
+ * to call register. The protocol comes from the fleet when the session
+ * connects, and each call's rules from its description; what the ship works
+ * on, the operator adds.
+ */
+function startingPromptText(input) {
+    const { mcpUrl, shipId, secret } = input;
+    return [
+        'You crew a ship in an Aeolus fleet.',
+        '',
+        `Fleet MCP URL: ${mcpUrl}`,
+        `Ship id: ${shipId}`,
+        `Ship secret: ${secret}`,
+        '',
+        "Its tools come from the fleet's MCP server at that URL. If this session has none of them, add the server with this command, then start the session again with this prompt:",
+        `claude mcp add --transport http --scope user aeolus ${mcpUrl}`,
+        '',
+        'Your location is where this session runs:',
+        "- DEVICE: a personal computer, such as the operator's laptop",
+        '- CLOUD: a hosted agent service, such as Claude Code on the web',
+        '- SERVER: a server the operator runs, such as a VPS',
+        '- OTHER: none of these, with a few words on where you run',
+        '',
+        'Call register.',
+    ].join('\n');
+}
+/**
+ * The crew lines: the same identity in one line for each harness with the
+ * aeolus plugin, which registers and keeps the crew token itself. The fleet
+ * URL is where the plugin reaches the fleet; it finds the MCP server and REST
+ * under it.
+ */
+function crewLines(input) {
+    const identity = `${input.fleetUrl} ${input.shipId} ${input.secret}`;
+    return [
+        { harness: 'claude-code', line: `/aeolus:crew ${identity}` },
+        { harness: 'codex', line: `$aeolus-crew ${identity}` },
+    ];
+}
+/** A starting prompt as the API hands it out: the prompt, its crew lines and the secret itself. */
+export function presentStartingPrompt(input) {
+    const { fleetUrl, shipId, secret } = input;
+    return {
+        shipId,
+        prompt: startingPromptText({ mcpUrl: mcpUrlOf(fleetUrl), shipId, secret }),
+        crewLines: crewLines({ fleetUrl, shipId, secret }),
+        secret,
+    };
+}
+//# sourceMappingURL=starting-prompt-text.js.map

package/dist/adapters/trpc/starting-prompt-text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"starting-prompt-text.js","sourceRoot":"","sources":["../../../src/adapters/trpc/starting-prompt-text.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAyD,MAAM,sBAAsB,CAAC;AAEvG;;;;;;GAMG;AAEH;;;;;;GAMG;AACH,SAAS,kBAAkB,CAAC,KAAyD;IACnF,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IACzC,OAAO;QACL,qCAAqC;QACrC,EAAE;QACF,kBAAkB,MAAM,EAAE;QAC1B,YAAY,MAAM,EAAE;QACpB,gBAAgB,MAAM,EAAE;QACxB,EAAE;QACF,4KAA4K;QAC5K,uDAAuD,MAAM,EAAE;QAC/D,EAAE;QACF,2CAA2C;QAC3C,8DAA8D;QAC9D,iEAAiE;QACjE,qDAAqD;QACrD,2DAA2D;QAC3D,EAAE;QACF,gBAAgB;KACjB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,SAAS,SAAS,CAAC,KAA2D;IAC5E,MAAM,QAAQ,GAAG,GAAG,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;IACrE,OAAO;QACL,EAAE,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,gBAAgB,QAAQ,EAAE,EAAE;QAC5D,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,gBAAgB,QAAQ,EAAE,EAAE;KACvD,CAAC;AACJ,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,qBAAqB,CAAC,KAA2D;IAC/F,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IAC3C,OAAO;QACL,MAAM;QACN,MAAM,EAAE,kBAAkB,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QAC1E,SAAS,EAAE,SAAS,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QAClD,MAAM;KACP,CAAC;AACJ,CAAC"}

package/dist/adapters/trpc/system.d.ts

@@ -0,0 +1,29 @@
+export declare const systemRouter: import("@trpc/server").TRPCBuiltRouter<{
+    ctx: import("./context.js").Context;
+    meta: import("./trpc.js").ProcedureMeta;
+    errorShape: import("@trpc/server").TRPCDefaultErrorShape | {
+        message: string;
+        data: {
+            requestId: string | undefined;
+            code: import("@trpc/server").TRPC_ERROR_CODE_KEY;
+            httpStatus: number;
+            path?: string;
+            stack?: string;
+        };
+        code: import("@trpc/server").TRPC_ERROR_CODE_NUMBER;
+    };
+    transformer: false;
+}, import("@trpc/server").TRPCDecorateCreateRouterOptions<{
+    /**
+     * Server time and fleet count: proves an authorised call reaches the database
+     * and back. Needs fleet:read, like every read about the fleet.
+     */
+    ping: import("@trpc/server").TRPCQueryProcedure<{
+        input: void;
+        output: {
+            serverTime: string;
+            fleetCount: number;
+        };
+        meta: import("./trpc.js").ProcedureMeta;
+    }>;
+}>>;

package/dist/adapters/trpc/system.js

@@ -0,0 +1,15 @@
+import { pingOutputSchema } from '@aeolus-fleet/common';
+import { router, scopedProcedure } from './trpc.js';
+export const systemRouter = router({
+    /**
+     * Server time and fleet count: proves an authorised call reaches the database
+     * and back. Needs fleet:read, like every read about the fleet.
+     */
+    ping: scopedProcedure('fleet:read')
+        .output(pingOutputSchema)
+        .query(async ({ ctx }) => {
+        const { serverTime, fleetCount } = await ctx.useCases.ping();
+        return { serverTime: serverTime.toISOString(), fleetCount };
+    }),
+});
+//# sourceMappingURL=system.js.map

package/dist/adapters/trpc/system.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system.js","sourceRoot":"","sources":["../../../src/adapters/trpc/system.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEpD,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC;IACjC;;;OAGG;IACH,IAAI,EAAE,eAAe,CAAC,YAAY,CAAC;SAChC,MAAM,CAAC,gBAAgB,CAAC;SACxB,KAAK,CAAC,KAAK,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE;QACvB,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QAC7D,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,WAAW,EAAE,EAAE,UAAU,EAAE,CAAC;IAC9D,CAAC,CAAC;CACL,CAAC,CAAC"}

package/dist/adapters/trpc/trpc.d.ts

@@ -0,0 +1,131 @@
+import type { Scope } from '@aeolus-fleet/common';
+import { type Caller, type Crew } from '../../domain/shared/caller.js';
+import type { DomainError } from '../../domain/shared/errors.js';
+import type { Result } from '../../domain/shared/result.js';
+import type { Context } from './context.js';
+/** All a caller learns of a server failure, with the request's id; the log keeps the rest under that id. */
+export declare const INTERNAL_ERROR_MESSAGE = "Internal error";
+/**
+ * What a procedure says about itself. A ship procedure's description is what
+ * an agent reads on every call, as an MCP tool or a REST operation: what it
+ * does and the rules for using it.
+ */
+export interface ProcedureMeta {
+    description: string;
+    /** Arguments the call takes as they stand, shown with the description and with a refusal of arguments that do not parse. */
+    example?: Readonly<Record<string, string>>;
+}
+/**
+ * What the console reads beside a refusal's code, to say more than "refused":
+ * that the operator signed in somewhere else, or when a rate-limited sign-in
+ * may try again (ISO 8601). Carried as the tRPC error's cause; the error data
+ * holds its fields.
+ */
+export declare class ConsoleRefusalDetails extends Error {
+    name: string;
+    readonly details: {
+        refusal?: 'SIGNED_IN_ELSEWHERE';
+        retryAt?: string;
+    };
+    constructor(details: {
+        refusal?: 'SIGNED_IN_ELSEWHERE';
+        retryAt?: string;
+    });
+}
+export declare const router: import("@trpc/server").TRPCRouterBuilder<{
+    ctx: Context;
+    meta: ProcedureMeta;
+    errorShape: import("@trpc/server").TRPCDefaultErrorShape | {
+        message: string;
+        data: {
+            requestId: string | undefined;
+            code: import("@trpc/server").TRPC_ERROR_CODE_KEY;
+            httpStatus: number;
+            path?: string;
+            stack?: string;
+        };
+        code: import("@trpc/server").TRPC_ERROR_CODE_NUMBER;
+    };
+    transformer: false;
+}>;
+/**
+ * The code a ship reads for a refusal whose tRPC code would hide it: a crew
+ * whose lease has ended reads LEASE_ENDED, not UNAUTHORIZED, so it can tell a
+ * released ship from a wrong crew token. The HTTP status stays the tRPC
+ * code's. The ship doors read it from the tRPC error's cause.
+ */
+export declare class ShipRefusalCode extends Error {
+    name: string;
+    readonly code: 'LEASE_ENDED';
+    constructor(code: 'LEASE_ENDED');
+}
+/** The value of a use case's result. A refusal becomes the matching tRPC error. */
+export declare function okOrThrow<T>(result: Result<T, DomainError>): T;
+/**
+ * A procedure that needs no caller: the base of every procedure, of the
+ * console procedures, and of `register`, which takes the ship secret.
+ *
+ * Postgres text can never store the character U+0000, so this one check at
+ * the door refuses it in any text input, as a bad request naming the field,
+ * before anything else reads the input.
+ */
+export declare const publicProcedure: import("@trpc/server").TRPCProcedureBuilder<Context, ProcedureMeta, {}, import("@trpc/server").TRPCUnsetMarker, import("@trpc/server").TRPCUnsetMarker, import("@trpc/server").TRPCUnsetMarker, import("@trpc/server").TRPCUnsetMarker, false>;
+/** A console procedure, signing in or out: it changes state, so it comes only from the console's origin. */
+export declare const consoleProcedure: import("@trpc/server").TRPCProcedureBuilder<Context, ProcedureMeta, {}, import("@trpc/server").TRPCUnsetMarker, import("@trpc/server").TRPCUnsetMarker, import("@trpc/server").TRPCUnsetMarker, import("@trpc/server").TRPCUnsetMarker, false>;
+/**
+ * Refuses a live subscription whose caller no longer holds: its console
+ * session ended, or its crew's lease did. A subscription outlives the call
+ * that opened it, so it asks again each time it has news.
+ */
+export declare function checkCallerStillHolds(ctx: Context): Promise<void>;
+/**
+ * A procedure for any caller, whatever its scopes: the base of every scoped
+ * procedure, and `whoami`, which tells a caller about itself. The caller comes
+ * from the server, never from the request.
+ */
+export declare const authenticatedProcedure: import("@trpc/server").TRPCProcedureBuilder<Context, ProcedureMeta, {
+    caller: Caller;
+}, import("@trpc/server").TRPCUnsetMarker, import("@trpc/server").TRPCUnsetMarker, import("@trpc/server").TRPCUnsetMarker, import("@trpc/server").TRPCUnsetMarker, false>;
+/**
+ * A procedure only a crew calls, with the crew token `register` gave it: one
+ * session crewing one ship under one lease. `deregister` needs nothing more,
+ * since a crew ends only its own lease. The console session is no crew token,
+ * so it is refused here.
+ */
+export declare const crewProcedure: import("@trpc/server").TRPCProcedureBuilder<Context, ProcedureMeta, {
+    crew: Crew;
+    caller: Crew;
+}, import("@trpc/server").TRPCUnsetMarker, import("@trpc/server").TRPCUnsetMarker, import("@trpc/server").TRPCUnsetMarker, import("@trpc/server").TRPCUnsetMarker, false>;
+/**
+ * A crew procedure that also needs the given scope: receiving and
+ * acknowledging deliveries, which a crew claims under its lease. argo's inbox
+ * comes with its own procedures.
+ */
+export declare function scopedCrewProcedure(scope: Scope): import("@trpc/server").TRPCProcedureBuilder<Context, ProcedureMeta, {
+    crew: Crew;
+    caller: Crew;
+}, import("@trpc/server").TRPCUnsetMarker, import("@trpc/server").TRPCUnsetMarker, import("@trpc/server").TRPCUnsetMarker, import("@trpc/server").TRPCUnsetMarker, false>;
+/**
+ * A procedure that needs the given scope. The caller and its scopes come from
+ * the server, never from the request, and are checked before any use case runs.
+ */
+export declare function scopedProcedure(scope: Scope): import("@trpc/server").TRPCProcedureBuilder<Context, ProcedureMeta, {
+    caller: Caller;
+}, import("@trpc/server").TRPCUnsetMarker, import("@trpc/server").TRPCUnsetMarker, import("@trpc/server").TRPCUnsetMarker, import("@trpc/server").TRPCUnsetMarker, false>;
+/**
+ * A procedure that needs any one of the given scopes: the few fleet calls a
+ * trierarch makes with `fleet:crew` beside the scope the console uses
+ * (decision 0002). Checked before any use case runs, as for one scope.
+ */
+export declare function anyScopeProcedure(...scopes: [Scope, Scope, ...Scope[]]): import("@trpc/server").TRPCProcedureBuilder<Context, ProcedureMeta, {
+    caller: Caller;
+}, import("@trpc/server").TRPCUnsetMarker, import("@trpc/server").TRPCUnsetMarker, import("@trpc/server").TRPCUnsetMarker, import("@trpc/server").TRPCUnsetMarker, false>;
+/**
+ * A procedure for a caller that crews its ship under a lease, with every given
+ * scope: argo's inbox, which its console session calls. A console session
+ * crews argo under the lease it holds; the use case refuses any ship but argo.
+ */
+export declare function scopedCrewCallerProcedure(...scopes: Scope[]): import("@trpc/server").TRPCProcedureBuilder<Context, ProcedureMeta, {
+    crew: Crew;
+    caller: Caller;
+}, import("@trpc/server").TRPCUnsetMarker, import("@trpc/server").TRPCUnsetMarker, import("@trpc/server").TRPCUnsetMarker, import("@trpc/server").TRPCUnsetMarker, false>;