@50arms/platform-mcp 0.1.439 → 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

@@ -881,14 +881,13 @@ strictTool("plan_connect",
     "(show the code, open the URL, then call again; it waits until this session ends; a call re-asks an expired one). " +
     "Signed in, the reply carries `owedComments` (person comments no agent has answered yet: read first, answer each, ack then reply) and `missedEvents` (operator " +
     "events no session had been told about: read next), " +
-    "`browserInstruction` (do it now), `briefing` (the plan's goals, rules, caveats, architecture " +
+    "`browserInstruction` (do it now), `briefing` (goals, rules, caveats, architecture " +
     "titles and a first page of open cards) and `listenerHealth` (when its `state` is not `healthy`, do its " +
-    "`nextStep`). A session is on at most one plan: connecting elsewhere moves it (`movedFrom` names the " +
-    "plan it left). A plan holds one live session: when another is on it the connect is refused " +
-    "`plan_has_live_session`, naming that session; do not retry: tell the person which session holds " +
-    "it and connect elsewhere. A session whose plan another took while it was quiet is refused its next `/api/plans/mine/...` call: connect elsewhere or ask the person. Afterwards `50arms_api` calls to `/api/plans/mine/...` act on this plan, no plan id. " +
-    "Connecting signs you in as a team agent: `agent`/`agentInstruction` say who you are. " +
-    "No agent to sign in as: `agent_needed` (none exists for you; propose one) or `agent_limit_reached` (the member's or team's cap on sessions signed in as an agent is full; the person ends another session or raises the cap), nothing connects: follow its `instruction`, " +
+    "`nextStep`), and `docsLandJob` (on a docs land assignment: the conflict job's text, or `unavailable` with why). A session is on at most one plan: connecting elsewhere moves it (`movedFrom` names the " +
+    "plan it left). A plan holds one live session: another on it refuses the connect (`plan_has_live_session`, " +
+    "naming that session); do not retry: tell the person and connect elsewhere. A session whose plan another took while it was quiet is refused its next `/api/plans/mine/...` call: connect elsewhere or ask the person. Afterwards `50arms_api` calls to `/api/plans/mine/...` act on this plan, no plan id. " +
+    "Connecting signs you in as a team agent (`agent`, `agentInstruction`). " +
+    "No agent to sign in as: `agent_needed` (none exists for you; propose one) or `agent_limit_reached` (the cap on agent sessions is full; the person ends another or raises it), nothing connects: follow its `instruction`, " +
     "no other dashboard work until `plan_connect` holds an agent. A `naming` block (status `needed`) gives the exact " +
     "`title`, `{Name}: PLAN-NNN {short title}`; rename this thread to it (`set_session_title`, or ask for `/rename`), then connect again with that `title`. " +
     // DX-4608 / DX-5549: a title in the format naming another agent than the held one is refused.
@@ -908,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()
@@ -927,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) {
@@ -1015,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.439", 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.439",
+  "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",