@50arms/platform-mcp 0.1.440 → 0.1.441

package/README.md

@@ -18,6 +18,7 @@ BOARD-ONLY (DX-1171): board is the first-level concept; repo is DERIVED from boa
 ## Signing in (DX-4390): request and approve
 
 An operator session has no stored credential. Signed out, `plan_connect` (optionally with `title`, the session's own Claude title) posts `POST /api/access-requests` and answers at once `{state: "approval_required", approvalUrl, confirmCode, expiresAt, instruction}`: show the user the code and open the URL; they approve in the dashboard. The server polls `POST /api/access-requests/claim` in the background, so the key is stored when the approval lands; the next `plan_connect` waits up to about 45 seconds for it, then connects, or answers `approval_pending`. One tool call never blocks for minutes. `denied` is reported once; a request that lapsed (the dashboard deletes it within about a minute of expiry, so a claim answers 404) starts a fresh one on the next call.
+- **A launch token (DX-6801, DEC-522).** `plan_connect` and `card_connect` take an optional `launch_token`: the one-use token the session that started this one passed in its prompt. A signed-out session given one redeems it once per process through the public `POST /api/access-requests/claim` with `{secret: <token>, labelId: <this session's id>}` (`labelId` is sent only on a redeem); `approved` stores the key like an approval and answers signed in, with no access request. Any other answer (`claimed`, `expired`, 404, 409 `launch_grant_refused` with its `reason`, 429) spends the token and falls through to the usual person's request, the answer carrying a `note` that names why the token was not used. A signed-in session ignores the token.
 
 - **Storage.** `~/.config/danxbot/session-keys/<sha12(dashboard url)>/<session id>.json`, mode 0600, written write-then-rename, pruned after 7 days. One file per dashboard and per session; this server reads it at boot, and `restart_notice` reads the same file through the `session-key` credential source and proves the fingerprint. The key lapses on the dashboard after 24 hours without use (every authenticated call, the relay's heartbeat included, renews it), and is revocable from the account page.
 - **A 401 on the stored key** deletes the file and returns the sign-in halt (in `plan_connect`: a new request in the same call). That is a key that lapsed. A key a PERSON revoked is answered `401 key_revoked` (DX-4418): the key file is deleted and EVERY dashboard tool, `plan_connect` included, returns one stop halt (who revoked it and when; commit work in progress and end; a dispatched agent makes no further call), for the rest of the process. No access request is made. The worker finds the revocation itself and ends the dispatch as revoked (every dashboard route, the dispatch-complete one included, refuses a revoked key). `plan_events_wait` answers `stopped` with the reason `key_revoked` the same way. **A 404 on create** means the dashboard predates request-and-approve and says so.

package/dist/access-request.js

@@ -74,9 +74,14 @@ export async function createAccessRequest(fetchImpl, dashboardUrl, input) {
         return { kind: "rate_limited", retryAfterSeconds: retryAfterSeconds(headers) };
     return { kind: "refused", status, body: json };
 }
-export async function claimAccessRequest(fetchImpl, dashboardUrl, secret) {
+/**
+ * DX-6801: `labelId` rides along ONLY when redeeming a launch token (the secret is then the token a parent session passed in this
+ * session's prompt, and `labelId` this session's id, which the dashboard stores the key under); a normal poll sends `{secret}` alone.
+ * A launch redeem the dashboard refuses answers 409 `launch_grant_refused` with a `reason`: that is a `refused` answer, body as sent.
+ */
+export async function claimAccessRequest(fetchImpl, dashboardUrl, secret, labelId) {
     const url = `${baseOf(dashboardUrl)}/api/access-requests/claim`;
-    const { status, headers, json } = await postPublic(fetchImpl, url, { secret });
+    const { status, headers, json } = await postPublic(fetchImpl, url, labelId === undefined ? { secret } : { secret, labelId });
     if (status === 404)
         return { kind: "not_found" };
     if (status === 429)

package/dist/index.js

@@ -907,6 +907,11 @@ strictTool("plan_connect",
     'The `naming` block\'s exact `{Name}: PLAN-NNN {short title}`, after renaming this thread. Omit on the first connect.'),
     assignment_id: z.number().int().positive().optional().describe("The assignment this connect answers, when a person's assignment message names one. Refused `assignment_ended` once it is over: then do nothing more about it."),
     disconnect: z.boolean().optional().describe("true = leave `plan_id` (your current plan); no `title`."),
+    launch_token: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("The one-use token the session that started this one passed in its prompt. With it a signed-out session signs in with no person approving it; a token that cannot be used says why and the session asks a person as usual. Omit it otherwise."),
     person_sign_in: z
         .boolean()
         .optional()
@@ -926,7 +931,7 @@ async (args) => {
         return haltResult("plan_connect: `disconnect: true` needs `plan_id`, the plan this session is currently on");
     }
     // DX-4390 — no key yet: ask for one (or wait for the approval already asked for).
-    const ready = await access.ensureAccess(args.title);
+    const ready = await access.ensureAccess(args.title, args.launch_token);
     if (!ready.signedIn)
         return accessReply(ready);
     if (args.plan_id === undefined) {
@@ -1014,8 +1019,13 @@ strictTool("card_connect",
         .describe("The `naming` block's exact `{Name}: {CARD-ID} {card title}`, after renaming this thread. Omit on the first connect."),
     assignment_id: z.number().int().positive().optional().describe("The assignment this connect answers, when a person's assignment message names one. Refused `assignment_ended` once it is over: then do nothing more about it."),
     disconnect: z.boolean().optional().describe("true = let go of `card_id` (the card you hold); no `title`."),
+    launch_token: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("The one-use token the session that started this one passed in its prompt. With it a signed-out session signs in with no person approving it; a token that cannot be used says why and the session asks a person as usual. Omit it otherwise."),
 }, async (args) => {
-    const ready = await access.ensureAccess(args.title);
+    const ready = await access.ensureAccess(args.title, args.launch_token);
     if (!ready.signedIn)
         return accessReply(ready);
     const result = spillRoleInstruction(await cardConnect(client, args));

package/dist/machine-toolkit.js

@@ -250,7 +250,7 @@ function resolveToolkitVersion(stamped, readManifest) {
   return stamped ?? readManifest();
 }
 var readOwnManifest = () => JSON.parse(readFileSync2(new URL("../../package.json", import.meta.url), "utf8")).version;
-var TOOLKIT_VERSION = resolveToolkitVersion(false ? void 0 : "0.1.440", readOwnManifest);
+var TOOLKIT_VERSION = resolveToolkitVersion(false ? void 0 : "0.1.441", readOwnManifest);
 function envelope(now) {
   return { contract_version: CONTRACT_VERSION, toolkit_version: TOOLKIT_VERSION, profile: PROFILE, measured_at: now.toISOString() };
 }

package/dist/session-access.js

@@ -56,6 +56,34 @@ const unknownTeamError = (team) => `the dashboard has no team "${team}" (DANXBOT
 const NO_SESSION_ID_ERROR = "this server has no CLAUDE_CODE_SESSION_ID, so it cannot request a session key";
 const CLAIMED_LOST_ERROR = "the dashboard says this request was already claimed, but this process never received the key; " +
     "start a new request";
+/** DX-6801: why a launch token signed nobody in; the session then asks a person as any signed-out session does. */
+const launchNote = (why) => `The launch token was not used: ${why}. This session asks a person to approve it instead: show the user the confirm code and URL.`;
+function launchRefusalWhy(claim) {
+    switch (claim.kind) {
+        case "claimed":
+            return "it was already redeemed (a launch token works once)";
+        case "expired":
+            return "it expired or was withdrawn";
+        case "not_found":
+            return "the dashboard does not know it";
+        case "denied":
+            return "the dashboard answered denied";
+        case "pending":
+            return "the dashboard answered pending, which a launch token never is";
+        case "rate_limited":
+            return `the dashboard rate limited the redeem (retry after ${claim.retryAfterSeconds}s) and a token is tried once per process`;
+        case "refused": {
+            const body = claim.body;
+            if (claim.status === 409 && body?.error === "launch_grant_refused") {
+                const missing = Array.isArray(body.missingPermissions) && body.missingPermissions.length > 0
+                    ? ` (missing permissions: ${body.missingPermissions.join(", ")})`
+                    : "";
+                return `the dashboard refused the launch grant: ${String(body.reason)}${missing}`;
+            }
+            return `the dashboard refused the redeem (${claim.status}): ${JSON.stringify(claim.body)}`;
+        }
+    }
+}
 const EXPIRED_NOTE = "The previous request expired before it was approved: the dashboard stopped hearing from this session. This is a new " +
     "request: show the user its new confirm code and URL.";
 export const defaultSleep = (ms) => new Promise((resolve) => {
@@ -76,6 +104,8 @@ export class SessionAccess {
     // DX-4390: two concurrent signed-out plan_connect calls must not each post a request.
     ensureQueue = Promise.resolve();
     lastKeyFileWrite = 0;
+    // DX-6801: a launch token is redeemed at most once per process, whatever the answer.
+    launchTokenTried = false;
     // DX-5882: why this server holds no credential (null while it holds one); logged with every "Not signed in" halt.
     signedOutCause = null;
     fetchImpl;
@@ -203,13 +233,17 @@ export class SessionAccess {
      * Make sure this session holds a key. Signed in: `{signedIn: true}`. Otherwise the answer
      * `plan_connect` returns: the request just made, the one still pending (after waiting up to
      * `awaitMs` for it), or why there is none. Calls run one at a time.
+     *
+     * DX-6801 / DEC-522: a signed-out session given the `launchToken` the session that started it passed in its prompt redeems it
+     * (once per process) through the public claim route, with no person approving. Any answer but `approved` spends the token and
+     * falls through to the person's request, the answer carrying a `note` that says why the token was not used.
      */
-    ensureAccess(title) {
-        const run = this.ensureQueue.then(() => this.ensureAccessNow(title));
+    ensureAccess(title, launchToken) {
+        const run = this.ensureQueue.then(() => this.ensureAccessNow(title, launchToken));
         this.ensureQueue = run.catch(() => undefined);
         return run;
     }
-    async ensureAccessNow(title) {
+    async ensureAccessNow(title, launchToken) {
         // DX-4418: a person revoked this session's access; it asks again only after `personSignIn` (DX-6894).
         const revokedHalt = this.revokedHalt();
         if (revokedHalt !== null)
@@ -221,6 +255,21 @@ export class SessionAccess {
             return notReady({ state: "no_session_id", error: NO_SESSION_ID_ERROR }, true);
         }
         let note;
+        // DX-6801: only while no request of this process is open (a person's approval already in flight stays the way in).
+        if (launchToken !== undefined && !this.launchTokenTried && this.pending === null) {
+            this.launchTokenTried = true;
+            const claim = await claimAccessRequest(this.fetchImpl, this.deps.dashboardUrl, launchToken, sessionId);
+            if (claim.kind === "approved") {
+                const stored = this.storeKey(claim.apiKey);
+                if (stored.kind === "approved")
+                    return { signedIn: true };
+                if (stored.kind === "failed")
+                    return notReady({ state: "request_failed", error: stored.error }, true);
+            }
+            else {
+                note = launchNote(launchRefusalWhy(claim));
+            }
+        }
         if (this.pending !== null) {
             const pending = this.pending;
             const outcome = await Promise.race([pending.settled, this.sleep(this.awaitMs).then(() => null)]);
@@ -238,7 +287,12 @@ export class SessionAccess {
                     note = EXPIRED_NOTE;
             }
         }
-        return this.createRequest(sessionId, title, note);
+        const created = await this.createRequest(sessionId, title, note);
+        // DX-6801: a refused or failed request carries the launch note too, so the reason is never lost.
+        if (note !== undefined && !created.signedIn && !("note" in created.answer)) {
+            return { ...created, answer: { ...created.answer, note } };
+        }
+        return created;
     }
     async createRequest(sessionId, title, note) {
         const created = await createAccessRequest(this.fetchImpl, this.deps.dashboardUrl, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@50arms/platform-mcp",
-  "version": "0.1.440",
+  "version": "0.1.441",
   "description": "Stdio MCP server fronting the 50 Arms dashboard API for agents (operator sessions and dispatched workers alike): the generic 50arms_api/50arms_api_list/50arms_api_spec tools reach any route the caller's credential may call, plus dedicated agent-specific tools (plan_connect, request_permission, attach_file, and 50arms_slack_reply) (DX-3465, PLN-11 R-25).",
   "license": "MIT",
   "type": "module",