@walkeros/mcp 4.6.0-next-1788817472881 → 4.6.0

package/README.md

@@ -55,8 +55,23 @@ npm install @walkeros/mcp
 
 The server starts, registers all tools, and runs the whole local loop without
 any credentials. `auth` reports `{ "authenticated": false }` and the local tools
-work regardless. Only the walkerOS cloud tools need a login, either through the
-`auth` tool's device code flow or a `WALKEROS_TOKEN` environment variable.
+work regardless. Only the walkerOS cloud tools need a credential.
+
+Two ways to get one:
+
+- **`auth` with `action: "login"`** runs the RFC 8628 device authorization
+  grant. It answers with a URL, you approve it in a browser you are already
+  signed in to, and a second call with the same `deviceCode` resumes polling
+  until the approval lands. The session that results refreshes itself, and it
+  appears in the app under Account, Connected apps, where disconnecting it takes
+  effect on the next call. `auth` with `action: "logout"` revokes it.
+- **`WALKEROS_TOKEN`** carries an automation token (`wos_pat_...`) minted in the
+  app under Account, then Automation tokens. It is used as-is and never
+  refreshed, which is what a CI job or a headless server wants.
+
+There is no endpoint that mints a token from another token, and nothing issues
+`sk-walkeros-` or `mcp-walkeros-` values any more; rows carrying them keep
+verifying until they expire.
 
 ## Quick start
 
@@ -133,11 +148,11 @@ Read these before writing a configuration by hand.
 
 ## Environment variables
 
-| Variable              | Required | Default                   | Purpose                                               |
-| --------------------- | -------- | ------------------------- | ----------------------------------------------------- |
-| `WALKEROS_TOKEN`      | No       | none                      | Bearer token, an alternative to the `auth` tool login |
-| `WALKEROS_PROJECT_ID` | No       | none                      | Active project ID (`proj_...`)                        |
-| `WALKEROS_APP_URL`    | No       | `https://app.walkeros.io` | Base URL override                                     |
+| Variable              | Required | Default                   | Purpose                                                                   |
+| --------------------- | -------- | ------------------------- | ------------------------------------------------------------------------- |
+| `WALKEROS_TOKEN`      | No       | none                      | Automation token (`wos_pat_...`), an alternative to the `auth` tool login |
+| `WALKEROS_PROJECT_ID` | No       | none                      | Active project ID (`proj_...`)                                            |
+| `WALKEROS_APP_URL`    | No       | `https://app.walkeros.io` | Base URL override                                                         |
 
 ## Programmatic usage
 

package/dist/index.d.ts

@@ -528,6 +528,19 @@ interface ToolClient {
     logout(): Promise<{
         deleted: boolean;
     }>;
+    /**
+     * The base URL of the walkerOS app this door talks to, without a trailing
+     * slash. REQUIRED: a tool that puts a link in front of a person has to name
+     * the backend it actually reached, and a door that cannot name itself would
+     * emit links into a chat transcript that point somewhere else. Making it
+     * required means the compiler, not a runtime surprise, catches that.
+     *
+     * Each door answers from its own world: the CLI-backed client resolves the
+     * user's machine (`WALKEROS_APP_URL`, then the CLI config file, then the
+     * built-in default), while an in-process host returns the URL it is served
+     * on. Never derive this from the local CLI inside a tool.
+     */
+    appBaseUrl(): string;
     checkHealth?(): Promise<{
         reachable: boolean;
         status?: string;
@@ -763,6 +776,14 @@ declare class HttpToolClient implements ToolClient {
     logout(): Promise<{
         deleted: boolean;
     }>;
+    /**
+     * The app this local door talks to: `WALKEROS_APP_URL`, then the CLI config
+     * file, then the built-in default, which is exactly the chain every other
+     * method here already resolves its base URL through. Normalized, because
+     * neither the env var nor the config file is obliged to omit a trailing
+     * slash and the interface promises a base without one.
+     */
+    appBaseUrl(): string;
     /**
      * Unauthenticated reachability probe of the app's PUBLIC `/api/health`
      * route. Uses a plain `fetch` (no `createApiClient`, whose every request
@@ -992,6 +1013,19 @@ interface FlowCanvasPayload {
         reason: string;
     };
     suggestions?: SuggestionTile[];
+    /**
+     * Absolute link to this flow's page in the app, from `links.flow`.
+     *
+     * Named for the `appBaseUrl()` seam it is built from, and never `url`: that
+     * is a field several app responses already use for something of their own
+     * (a deployment's `url` is where it SERVES), and one key meaning one thing
+     * across every tool is what keeps a link from ever landing on top of it.
+     *
+     * Optional because a tool that cannot name the project or the flow emits no
+     * link rather than a guess, and because the in-app chat renders the canvas
+     * itself and has no use for a link to the page it is already on.
+     */
+    appUrl?: string;
 }
 interface FlowCanvasToolResult extends FlowCanvasPayload {
     kind: 'flow-canvas';
@@ -1013,6 +1047,135 @@ declare function flowCanvasResult(payload: FlowCanvasPayload): {
 };
 declare function isFlowCanvasResult(v: unknown): v is FlowCanvasToolResult;
 
+/**
+ * Addresses of walkerOS app screens, built in one place so every tool hands a
+ * person the same link for the same screen.
+ *
+ * WHY THIS EXISTS. A tool that names a release, a step, or a deployment in
+ * prose leaves the person to go find it. A link ends that: the answer and the
+ * screen it is about arrive together. Building the address in each tool would
+ * instead give as many spellings of `/projects/.../flows/...` as there are
+ * emission points, and the first one to drift would send someone to a 404 that
+ * no test here could see.
+ *
+ * THE BASE URL IS CONSUMED RAW. `client.appBaseUrl()` is already normalized by
+ * the door that answers it (the CLI-backed door wraps `resolveAppUrl()` in
+ * `normalizeBaseUrl`; the hosted door returns the same expression it publishes
+ * as its OAuth issuer, which cannot carry a trailing slash). Normalizing again
+ * here would put a second opinion about the shape in the system, which is
+ * exactly what one normalization point per door exists to prevent.
+ *
+ * ONE DEFINITION, BOTH DOORS. Nothing here branches on which door is calling.
+ * The base URL is the only thing that differs between them, and it arrives as
+ * an argument.
+ *
+ * EVERY LINK IS ABSOLUTE. These land in a chat transcript, where a path
+ * relative to nothing is useless.
+ *
+ * AN UNBUILDABLE LINK IS `undefined`, NEVER A GUESS. Every builder returns
+ * `undefined` when it cannot name a screen that exists, and callers spread the
+ * field conditionally so the result simply carries no link. A link that lands
+ * on a 404, or on the app's "can't open that" notice, is worse than no link:
+ * it costs the person a click and teaches them the tool's links are unreliable.
+ *
+ * THE URL SHAPES ARE THE APP'S, NOT OURS. They mirror what the app routes
+ * today: `/projects/{projectId}/flows/{flowId}` and
+ * `/projects/{projectId}/deployments/{deploymentId}`, with a view on the flow
+ * page addressed by the `view` query param whose value names a SUBJECT
+ * (`variables`, `secrets`, `contract`, `history`, `releases`, `knowledge`,
+ * `step`). A step is `?view=step&flow=<named flow>&step=<type.name>`, the same
+ * vocabulary `hub_manage` already takes as its `flow` and `step` params.
+ */
+/** A flow page: the address every flow-scoped view hangs off. */
+interface FlowLinkTarget {
+    /** From `client.appBaseUrl()`. Consumed as given. */
+    baseUrl: string;
+    projectId: string;
+    flowId: string;
+}
+/**
+ * One step inside a flow. `flow` is the named flow within the config ("web",
+ * "server"); `step` is `"type.name"`, e.g. `"destination.ga4"`.
+ */
+interface StepLinkTarget extends FlowLinkTarget {
+    step: string;
+    /**
+     * Null and undefined both mean "the caller did not name one", which is the
+     * shape `hub_manage`'s step history answers with when it was not filtered by
+     * flow.
+     */
+    flow?: string | null;
+}
+/** One discussion thread, addressed by what it hangs on. */
+interface ThreadLinkTarget extends FlowLinkTarget {
+    anchorType: string;
+}
+/**
+ * One deployment.
+ *
+ * Pass the `dep_...` id, not the slug. The detail route resolves either, but
+ * the page's live-status stream matches on the id alone, so a slug link opens a
+ * page whose status stream fails while the deployment is still deploying. This
+ * builder does not inspect the value: naming the id is the caller's job.
+ */
+interface DeploymentLinkTarget {
+    baseUrl: string;
+    projectId: string;
+    deploymentId: string;
+}
+declare const links: {
+    /** The flow page itself. `undefined` when any part of the address is empty. */
+    flow(target: FlowLinkTarget): string | undefined;
+    /**
+     * The screen showing one step.
+     *
+     * A `contract` step, in any of its spellings, is answered with the CONTRACT
+     * view rather than a step address. `?view=step&step=contract.checkout` is a
+     * legitimate address in the vocabulary this tool speaks, but the app has
+     * deliberately deferred opening ONE contract entry and refuses that link with
+     * a notice. `?view=contract` opens the contract editor the entry lives in,
+     * which is the nearest screen that actually exists. A `flow` alongside a
+     * contract step is a caller mistake (contract entries are top-level) and is
+     * ignored rather than turned into a refused link.
+     *
+     * Otherwise a step needs its named flow: `type.name` alone is not unique in a
+     * config holding both a web and a server flow, and the app resolves an
+     * address without one to nothing and says so on screen. So an unnamed flow
+     * yields `undefined` here. Callers that want the link can re-ask with `flow`.
+     *
+     * What this cannot check is whether the step is still IN that flow. The
+     * address is resolved against the live config when the page opens, and a step
+     * since renamed or removed gets a notice there rather than a broken screen.
+     */
+    step(target: StepLinkTarget): string | undefined;
+    /**
+     * The release history of a flow.
+     *
+     * The app has no address for ONE release: `?view=releases` declares no params
+     * and opens the list the release is a row of. That is the screen a person
+     * asking about a release wants to be on, so this takes the flow and nothing
+     * else rather than pretending to a precision the app does not have.
+     */
+    release(target: FlowLinkTarget): string | undefined;
+    /**
+     * The screen a thread is read on.
+     *
+     * Only a release anchor can be addressed from the wire shape this tool
+     * holds. The app renders release-anchored discussions inside the release
+     * history, beside the release they hang on. Step and entity-action anchors
+     * have no surface at all yet. A TAG anchor does have one, the knowledge list
+     * on `?view=knowledge`, but only when the thread was captured in Tag Mode
+     * and carries a frame: `HubThreadWire` has no `frameId`, so nothing here can
+     * tell such a thread from one written over MCP against a null frame, and a
+     * knowledge link would open a list the thread may be absent from. So
+     * everything but a release anchor gets no link rather than a possibly empty
+     * one.
+     */
+    thread(target: ThreadLinkTarget): string | undefined;
+    /** One deployment's detail page. */
+    deployment(target: DeploymentLinkTarget): string | undefined;
+};
+
 declare module '@walkeros/core' {
     interface SourceMap {
         mcp: {
@@ -1036,4 +1199,4 @@ declare module '@walkeros/core' {
  */
 declare function createToolHandlers(client: ToolClient, packageVersion?: string): Record<string, ToolSpec>;
 
-export { type CreateServerOptions, type CreateStreamableHttpHandlerOptions, FEATURE_NOT_AVAILABLE, FRAME_HINT_EXTENDS_BASE, FRAME_HINT_MARK_SPACE, FRAME_HINT_NAMES_ARE_DOCUMENTATION, FRAME_HINT_NONE_ON_PAGE, FRAME_HINT_NONE_YET, FRAME_HINT_OPEN_PAGE_OR_GET, FRAME_HINT_READ_KNOWLEDGE, FRAME_MANAGE_DESCRIPTION, FRAME_MANAGE_INPUT_SCHEMA, FRAME_NOT_FOUND_HINT, type FlowCanvasPayload, type FlowCanvasToolResult, type FrameLeanListWire, type FrameLeanWire, type FrameListWire, type FrameWire, type GatedFeature, HINT_EMPTY_FEED, HINT_ENDED, HINT_NO_WINDOW, HINT_PREVIEW_STREAMS, HINT_READ, HINT_SIMULATE_FIRST, HINT_STOP, HUB_HINT_CONFIRM_INDEX, HUB_HINT_ENTRY_NAMES_FLOW, HUB_HINT_KEEP_ONE_THREAD, HUB_HINT_KNOWLEDGE_INDEX, HUB_HINT_KNOWLEDGE_PAGE_CAPPED, HUB_HINT_KNOWLEDGE_READ_ONLY, HUB_HINT_MASKED_ONLY, HUB_HINT_MESSAGES_TRUNCATED, HUB_HINT_MESSAGE_VISIBLE, HUB_HINT_NOTHING_DISCUSSED, HUB_HINT_NOTHING_WRITTEN, HUB_HINT_NO_MATCH, HUB_HINT_NO_THREAD_ON_ANCHOR, HUB_HINT_OPEN_RELEASE, HUB_HINT_RATIONALE_VISIBLE, HUB_HINT_READ_BACK, HUB_HINT_READ_FRAME, HUB_HINT_RELEASE_GET, HUB_HINT_REPLY_OR_OPEN, HUB_HINT_RESOLVE_IN_APP, HUB_HINT_ROWS_ARE_DEPLOYMENTS, HUB_HINT_SCAN_CAPPED, HUB_HINT_STAYS_RESOLVED, HUB_HINT_STEP_HISTORY, HUB_HINT_THREADS_INDEX, HUB_HINT_THREADS_PAGE_CAPPED, HUB_HINT_THREAD_OPEN, HUB_HINT_TRACE_STEP, HUB_HINT_WRITE_RATIONALE, HUB_MANAGE_DESCRIPTION, HUB_MANAGE_INPUT_SCHEMA, HUB_NOT_FOUND_HINT, HttpToolClient, type HubThreadWire, type JourneysResult, type KnowledgeEntryWire, type ListKnowledgeWire, type ListThreadsWire, type Logger, DESCRIPTION as OBSERVE_SESSION_DESCRIPTION, type RedactOptions, type ReleaseDetailWire, type ReleaseIndexWire, type ReleaseRef, type StepHistoryWire, type SuggestionTile, TOOL_DEFINITIONS, type ToolAnnotations, type ToolClient, type ToolDefinition, type ToolSpec, type VersionAnnotationWire, createStreamableHttpHandler, createToolHandlers, createWalkerOSMcpServer, featureDenialHint, flowCanvasResult, isFeatureDenial, isFlowCanvasResult, redactNestedStrings, wrapUserData };
+export { type CreateServerOptions, type CreateStreamableHttpHandlerOptions, type DeploymentLinkTarget, FEATURE_NOT_AVAILABLE, FRAME_HINT_EXTENDS_BASE, FRAME_HINT_MARK_SPACE, FRAME_HINT_NAMES_ARE_DOCUMENTATION, FRAME_HINT_NONE_ON_PAGE, FRAME_HINT_NONE_YET, FRAME_HINT_OPEN_PAGE_OR_GET, FRAME_HINT_READ_KNOWLEDGE, FRAME_MANAGE_DESCRIPTION, FRAME_MANAGE_INPUT_SCHEMA, FRAME_NOT_FOUND_HINT, type FlowCanvasPayload, type FlowCanvasToolResult, type FlowLinkTarget, type FrameLeanListWire, type FrameLeanWire, type FrameListWire, type FrameWire, type GatedFeature, HINT_EMPTY_FEED, HINT_ENDED, HINT_NO_WINDOW, HINT_PREVIEW_STREAMS, HINT_READ, HINT_SIMULATE_FIRST, HINT_STOP, HUB_HINT_CONFIRM_INDEX, HUB_HINT_ENTRY_NAMES_FLOW, HUB_HINT_KEEP_ONE_THREAD, HUB_HINT_KNOWLEDGE_INDEX, HUB_HINT_KNOWLEDGE_PAGE_CAPPED, HUB_HINT_KNOWLEDGE_READ_ONLY, HUB_HINT_MASKED_ONLY, HUB_HINT_MESSAGES_TRUNCATED, HUB_HINT_MESSAGE_VISIBLE, HUB_HINT_NOTHING_DISCUSSED, HUB_HINT_NOTHING_WRITTEN, HUB_HINT_NO_MATCH, HUB_HINT_NO_THREAD_ON_ANCHOR, HUB_HINT_OPEN_RELEASE, HUB_HINT_RATIONALE_VISIBLE, HUB_HINT_READ_BACK, HUB_HINT_READ_FRAME, HUB_HINT_RELEASE_GET, HUB_HINT_REPLY_OR_OPEN, HUB_HINT_RESOLVE_IN_APP, HUB_HINT_ROWS_ARE_DEPLOYMENTS, HUB_HINT_SCAN_CAPPED, HUB_HINT_STAYS_RESOLVED, HUB_HINT_STEP_HISTORY, HUB_HINT_THREADS_INDEX, HUB_HINT_THREADS_PAGE_CAPPED, HUB_HINT_THREAD_OPEN, HUB_HINT_TRACE_STEP, HUB_HINT_WRITE_RATIONALE, HUB_MANAGE_DESCRIPTION, HUB_MANAGE_INPUT_SCHEMA, HUB_NOT_FOUND_HINT, HttpToolClient, type HubThreadWire, type JourneysResult, type KnowledgeEntryWire, type ListKnowledgeWire, type ListThreadsWire, type Logger, DESCRIPTION as OBSERVE_SESSION_DESCRIPTION, type RedactOptions, type ReleaseDetailWire, type ReleaseIndexWire, type ReleaseRef, type StepHistoryWire, type StepLinkTarget, type SuggestionTile, TOOL_DEFINITIONS, type ThreadLinkTarget, type ToolAnnotations, type ToolClient, type ToolDefinition, type ToolSpec, type VersionAnnotationWire, createStreamableHttpHandler, createToolHandlers, createWalkerOSMcpServer, featureDenialHint, flowCanvasResult, isFeatureDenial, isFlowCanvasResult, links, redactNestedStrings, wrapUserData };