@walkeros/mcp 4.3.1 → 4.3.2

package/dist/index.d.ts

@@ -35,6 +35,71 @@ interface JourneysResult {
     journeys: Journey[];
     gaps: JourneyGap[];
 }
+/** Observation verbosity a session's container is provisioned with. */
+type ObserveLevel = 'off' | 'standard' | 'trace';
+/**
+ * The session's web part. Present once a preview arm is attached; null while
+ * the window has no web half. `credential` and the server `env` trio are
+ * connect secrets: the tool layer reads the part for arm presence and never
+ * surfaces them.
+ */
+interface ObserveSessionWebPart {
+    activationUrl: string | null;
+    credential: string;
+    previewEnabled: boolean;
+    bundleUrl: string;
+    /** Observer both arms post to, in the field name a `config.observe` declares. */
+    url?: string;
+    /** Project binding the collector cross-checks an arriving credential against. */
+    binding?: string;
+}
+/** The session's container part. Present once a container arm is provisioned. */
+interface ObserveSessionServerPart {
+    endpoint: string | null;
+    env: {
+        WALKEROS_OBSERVER_URL: string;
+        WALKEROS_DEPLOYMENT_ID: string;
+        WALKEROS_INGEST_TOKEN: string;
+    };
+}
+/**
+ * One Observe session: a time-boxed window on a flow that runtimes attach to
+ * as arms. `observedFlowName`/`serverFlowName` name the settings each arm runs;
+ * `web`/`server` being non-null is what makes an arm attached. Mirrors the
+ * app's session envelope.
+ */
+interface ObserveSessionResult {
+    id: string;
+    projectId: string;
+    flowId: string;
+    status: string;
+    errorMessage: string | null;
+    observedFlowName: string | null;
+    serverFlowName: string | null;
+    web: ObserveSessionWebPart | null;
+    server: ObserveSessionServerPart | null;
+    expiresAt: string;
+    recordsReceived: number;
+    createdAt: string;
+}
+/**
+ * Start a session on one flow. `settingsName` is the single knob the window is
+ * opened on: the flow's topology under that name decides which arms the app
+ * provisions, so the tool layer translates its arms input into this one field.
+ */
+interface StartObserveSessionOptions {
+    projectId: string;
+    flowId: string;
+    settingsName: string;
+    origins?: string[];
+    level?: ObserveLevel;
+    replace?: boolean;
+}
+interface ObserveSessionRef {
+    projectId: string;
+    flowId: string;
+    sessionId: string;
+}
 /**
  * Transport-agnostic client for network-reach MCP tools. The stdio build
  * plugs in HttpToolClient (talks to the walkerOS app over HTTPS via the
@@ -129,6 +194,16 @@ interface ToolClient {
         traceId?: string;
         limit?: number;
     }): Promise<JourneysResult>;
+    /**
+     * Observe session lifecycle. OPTIONAL as a trio: a client that cannot reach
+     * the session endpoints omits all three, and the `observe_session` handler
+     * guards on presence before calling. Reads stay with `listJourneys`, which
+     * doubles as the flow-to-live-window resolver (`observe_sessions.flow_id` is
+     * UNIQUE, so its `sessionId` IS the flow's live window).
+     */
+    startObserveSession?(options: StartObserveSessionOptions): Promise<ObserveSessionResult>;
+    getObserveSession?(options: ObserveSessionRef): Promise<ObserveSessionResult>;
+    endObserveSession?(options: ObserveSessionRef): Promise<void>;
     requestDeviceCode(): Promise<DeviceCodeResult>;
     pollForToken(deviceCode: string, options?: {
         timeoutMs?: number;
@@ -290,6 +365,15 @@ declare class HttpToolClient implements ToolClient {
         traceId?: string;
         limit?: number;
     }): Promise<JourneysResult>;
+    /**
+     * Observe session lifecycle over the CLI's authenticated boundary. The trio
+     * routes through the same `apiFetch` as every other method here, so token
+     * resolution, base URL, and `ApiError` shaping (which `isAuthError` reads)
+     * stay identical to the rest of the client.
+     */
+    startObserveSession(options: StartObserveSessionOptions): Promise<ObserveSessionResult>;
+    getObserveSession(options: ObserveSessionRef): Promise<ObserveSessionResult>;
+    endObserveSession(options: ObserveSessionRef): Promise<void>;
     requestDeviceCode(): Promise<DeviceCodeResult>;
     pollForToken(deviceCode: string, options?: {
         timeoutMs?: number;
@@ -335,6 +419,25 @@ interface CreateStreamableHttpHandlerOptions extends WebStandardStreamableHTTPSe
  */
 declare function createStreamableHttpHandler(server: McpServer, opts?: CreateStreamableHttpHandlerOptions): (request: Request) => Promise<Response>;
 
+/**
+ * Exported so the hosted plane can assert parity against this exact string
+ * instead of retyping it.
+ */
+declare const DESCRIPTION: string;
+/**
+ * Hints carry the verb ladder rather than the description. Module constants so
+ * the wording is one string per idea, quotable verbatim, and identical across
+ * planes. Exported so the hosted plane imports them instead of retyping them,
+ * which makes cross-plane parity a compiler concern.
+ */
+declare const HINT_SIMULATE_FIRST = "Simulate before preview: flow_simulate checks mapping with no browser.";
+declare const HINT_PREVIEW_STREAMS = "Preview streams into this session: mint a link with flow_manage preview_regrant, then open it on your site.";
+declare const HINT_READ = "Read with observe_journeys (flowId); it is the only read.";
+declare const HINT_STOP = "End both arms with observe_session stop.";
+declare const HINT_EMPTY_FEED = "recordsReceived is 0: nothing has reached the feed yet. Drive traffic on an attached arm.";
+declare const HINT_ENDED = "Session ended and both arms detached. Start a new one with observe_session start.";
+declare const HINT_NO_WINDOW = "No Observe session on this flow. Open one with observe_session start.";
+
 /**
  * Wraps a user-writable string in `<user_data>…</user_data>` so the chat
  * assistant treats it as data, never as instructions. Inner `</user_data>`
@@ -418,4 +521,4 @@ declare module '@walkeros/core' {
  */
 declare function createToolHandlers(client: ToolClient, packageVersion?: string): Record<string, ToolSpec>;
 
-export { type CreateServerOptions, type CreateStreamableHttpHandlerOptions, type FlowCanvasPayload, type FlowCanvasToolResult, HttpToolClient, type JourneysResult, type Logger, type RedactOptions, type SuggestionTile, TOOL_DEFINITIONS, type ToolAnnotations, type ToolClient, type ToolDefinition, type ToolSpec, createStreamableHttpHandler, createToolHandlers, createWalkerOSMcpServer, flowCanvasResult, isFlowCanvasResult, redactNestedStrings, wrapUserData };
+export { type CreateServerOptions, type CreateStreamableHttpHandlerOptions, type FlowCanvasPayload, type FlowCanvasToolResult, HINT_EMPTY_FEED, HINT_ENDED, HINT_NO_WINDOW, HINT_PREVIEW_STREAMS, HINT_READ, HINT_SIMULATE_FIRST, HINT_STOP, HttpToolClient, type JourneysResult, type Logger, DESCRIPTION as OBSERVE_SESSION_DESCRIPTION, type RedactOptions, type SuggestionTile, TOOL_DEFINITIONS, type ToolAnnotations, type ToolClient, type ToolDefinition, type ToolSpec, createStreamableHttpHandler, createToolHandlers, createWalkerOSMcpServer, flowCanvasResult, isFlowCanvasResult, redactNestedStrings, wrapUserData };