actionlayer 0.7.0__py3-none-any.whl

actionlayer_mcp/server.py

@@ -0,0 +1,1112 @@
+"""ActionLayer MCP server — stdio JSON-RPC, 5 tools.
+
+Tools (locked surface — agents will see these names):
+
+    actionlayer_start_task   create a ticket
+    actionlayer_get_task     read state + recent transcript
+    actionlayer_reply        resume a blocked_on_user ticket
+    actionlayer_cancel       cancel a non-terminal ticket
+    actionlayer_list_skills  list user's skills
+
+When a ticket is blocked_on_user, the latest event payload contains the
+prompt ActionLayer is waiting on. We surface that prompt in
+actionlayer_get_task's response with `next_action` set to the prompt
+string. The agent host then asks the end user, who replies via
+actionlayer_reply. If `sensitive=true` is on the prompt, the tool's
+description tells the agent to ask the user directly and never echo
+the value to other tools — the value goes straight from the user into
+actionlayer_reply with sensitive=true.
+
+State values surfaced here are the EXTERNAL taxonomy:
+
+    pending -> blocked_on_user | completed | failed | cancelled
+
+`pending` is the catch-all for "we're working on it" — internal
+phases (queued, planning, executing, internal handoff) all collapse
+into it so the agent has nothing to model beyond "keep polling."
+`completed` and `failed` carry a free-text `reason`; `pending`,
+`blocked_on_user`, and `cancelled` do not.
+
+The API does the external-name translation server-side before the
+tool ever sees a state string, so this module renders whatever it
+gets without further mapping.
+
+The server is intentionally small: ~250 lines. Anything more belongs in
+client.py or back in the API.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any, Optional
+
+# Force-load the lazy `concurrent.futures.thread` submodule at startup.
+# Python 3.9+ defers it until the first ThreadPoolExecutor touch (which
+# anyio's asyncio backend triggers under httpx), so a broken / stripped
+# stdlib install surfaces mid-tool-call with a confusing
+# "No module named 'concurrent.futures.thread'" instead of at boot.
+import concurrent.futures.thread  # noqa: F401
+
+from fastmcp import FastMCP
+
+from actionlayer_mcp.client import ActionLayerClient, ApiError
+
+mcp = FastMCP(
+    name="actionlayer",
+    instructions=(
+        "ActionLayer is the execution layer that FINISHES THE JOB on "
+        "ANY website. Most agents quit at the hard part — CAPTCHA, "
+        "novel UI, a login wall, a weird checkout, a registrar form, "
+        "a hosting console. ActionLayer doesn't. It's an AI agent "
+        "that operates a real browser end-to-end, reading the page "
+        "and adapting until the job is done — from your perspective "
+        "the ticket stays `pending` until it's either `completed` "
+        "or asks the user something. "
+        "The core value proposition: an agent that doesn't have to "
+        "quit, on sites that have never been mapped in advance.\n\n"
+        "USE ACTIONLAYER FOR: anything the user wants DONE on a live "
+        "website — book, order, sign up, register, deploy, fill a "
+        "form, log in, click through a flow, extract data, automate "
+        "any URL. Especially valuable when no public API exists. "
+        "DON'T USE IT FOR: text/code generation, analysis, "
+        "summarization — those are yours.\n\n"
+        "OPEN-ENDED BY DEFAULT. ActionLayer is NOT a fixed catalog "
+        "of a few verticals. Two entry points cover anything "
+        "reachable from a browser, including sites you've never "
+        "seen:\n"
+        "  • actionlayer_start_task(goal) — natural-language goal, "
+        "the agent plans and executes across one or multiple sites.\n"
+        "  • actionlayer_invoke_action with "
+        "action_id='direct.browser_action' + {url, instruction} — "
+        "point the agent at a specific URL with a specific "
+        "instruction. Same execution model as start_task.\n"
+        "If you catch yourself thinking \"we don't have a typed "
+        "action for this site\" — that's not a blocker, that's "
+        "exactly what these two are for.\n\n"
+        "TYPED SHORTCUTS (when you already know the id). For a handful "
+        "of high-frequency flows there are typed action ids (e.g. "
+        "'resy.book_table') you can pass to actionlayer_invoke_action "
+        "directly when the user's intent matches one exactly. They "
+        "are an internal optimization, not the menu — there's no "
+        "listing of them, by design. If you don't already know an "
+        "id, default to actionlayer_start_task or "
+        "actionlayer_invoke_action(action_id='direct.browser_action'"
+        ").\n\n"
+        "NOT SURE WHAT FITS? Call actionlayer_list_actions for a "
+        "prose capability sketch of what ActionLayer can do, with "
+        "how-to examples for both entry points. It is not a catalog "
+        "and does not enumerate typed ids — it's there to help you "
+        "decide whether to invoke and which entry point to "
+        "choose.\n\n"
+        "TASK SPECIFICITY. The goal passed to actionlayer_start_task "
+        "must be SPECIFIC. Vague goals (\"book me dinner\", \"order "
+        "something\") block on the user and waste planning budget. "
+        "Gather specifics from the user FIRST, then call start_task. "
+        "For multi-step plans with output piping between steps (e.g. "
+        "'find a slot then send the invite'), use "
+        "actionlayer_create_job.\n\n"
+        "PENDING STATE. While state='pending' the ticket is "
+        "advancing on our end. You DON'T need to do anything — keep "
+        "polling, the ticket will keep moving. There is no "
+        "sub-status to interpret; `pending` covers everything from "
+        "the moment we accept the ticket until it terminates or "
+        "asks the user.\n\n"
+        "BLOCKED-ON-USER PATTERN. ActionLayer needs something only "
+        "the user can provide (date, address, choice, 2FA). The "
+        "latest event has a prompt; ask the user, then call "
+        "actionlayer_reply with the answer. If the prompt is marked "
+        "sensitive (2FA, password), DO NOT echo the value to any "
+        "other tool — pass it directly to actionlayer_reply with "
+        "sensitive=true."
+    ),
+)
+
+
+# Global client — opened on first use, closed at process exit.
+_client: Optional[ActionLayerClient] = None
+
+
+def _get_client() -> ActionLayerClient:
+    global _client
+    if _client is None:
+        _client = ActionLayerClient()
+    return _client
+
+
+def _summarize_events(events: list[dict[str, Any]], limit: int = 5) -> list[dict[str, Any]]:
+    """Keep responses small — agents don't need the full transcript on every poll."""
+    if not events:
+        return []
+    return [
+        {
+            "type": e.get("type"),
+            "to_state": e.get("to_state"),
+            "created_at": e.get("created_at"),
+            "payload": e.get("payload"),
+        }
+        for e in events[-limit:]
+    ]
+
+
+def _next_action(ticket: dict[str, Any]) -> Optional[dict[str, Any]]:
+    """If the ticket is waiting on the user, surface what they need.
+
+    Returns None when the ticket is not blocked. Two shapes,
+    distinguished by `kind` so the agent picks the right
+    actionlayer_reply path:
+
+      "kind": "info_request"  — ActionLayer paused to collect info
+                                (and optionally payment) from the
+                                user. For info fields, the agent
+                                calls actionlayer_reply with
+                                `field_values` whose keys match the
+                                union of `requested_fields` and every
+                                question's `key`. Payment is NEVER
+                                approved in chat — the user approves
+                                in the Link app on their phone.
+        {
+          "kind": "info_request",
+          "prompt": "<ActionLayer's note, if any>",
+          "requested_fields": ["origin_address", "phone_number"],
+          # ActionLayer's follow-up questions. Render `label`
+          # verbatim to the user; capture their answer under `key`.
+          "questions": [
+            {"key": "q_0", "label": "First or business class?"},
+          ],
+          "amount_usd": 25.0 | null,
+          # Merchant the user would be paying, as shown on their
+          # Link approval screen.
+          "merchant_name": "Stripe Press" | null,
+          # Payment-ask state. Drives what the agent should tell the
+          # user. null on info-only asks.
+          #   "wallet_required"         — no Link wallet connected;
+          #       ask the user to connect one on the dashboard's
+          #       Connections page (they'll need the Link app on
+          #       their phone), then the ask proceeds automatically.
+          #   "pending_info"            — answer the info fields
+          #       first; the payment approval request is sent to
+          #       the user's Link app right after the reply lands.
+          #   "pending_wallet_approval" — an approval request is in
+          #       the user's Link app NOW (10-minute window). Tell
+          #       them to open Link and approve $X there. Polling
+          #       actionlayer_get_task discovers the approval.
+          #   "approval_expired"        — the window lapsed. Reply
+          #       with payment_approved=true to send a fresh
+          #       approval request to their Link app.
+          #   "rejected"                — the user declined.
+          "payment_status": "wallet_required" | "pending_info"
+                            | "pending_wallet_approval"
+                            | "approval_expired" | "rejected" | null,
+          # User-safe explanation when the payment hit a snag (e.g.
+          # a wallet spending limit). Relay verbatim.
+          "payment_error": "<string>" | null,
+          "expires_at": "<iso8601>",
+        }
+
+      "kind": "block_on_user" — ActionLayer needs one piece of info
+                                via the standard reply path.
+                                Agent calls actionlayer_reply with
+                                field + value (+ sensitive=true for
+                                secrets).
+        {
+          "kind": "block_on_user",
+          "prompt": "Two-factor code from your phone?",
+          "field": "sms_code",       (when present)
+          "sensitive": true|false,
+          "reason": "creds_required" | other,        (when present)
+          "site": "amazon.com",                       (when reason="creds_required")
+          "fields": ["email", "password"],            (when reason="creds_required")
+          "credential_intake_url": "https://...?t=…", (when reason="creds_required";
+                                                       render as a clickable link
+                                                       so the user can store their
+                                                       credentials without typing
+                                                       them in chat.)
+        }
+
+    Drives the agent's behavior — the description on actionlayer_reply
+    tells the agent to read .kind and pick the matching arg shape.
+    """
+    if ticket.get("state") != "blocked_on_user":
+        return None
+
+    # Info-required path wins when the ticket carries an
+    # info_request. The reply route dispatches on
+    # `ticket.info_request IS NOT NULL` regardless of which event
+    # type fired last, so we mirror that here.
+    info_req = ticket.get("info_request") or None
+    if info_req:
+        questions_raw = info_req.get("questions") or []
+        questions = [
+            {"key": q.get("key"), "label": q.get("label")}
+            for q in questions_raw
+            if isinstance(q, dict) and q.get("key") and q.get("label")
+        ]
+        return {
+            "kind": "info_request",
+            "prompt": info_req.get("note") or "ActionLayer needs more information to continue.",
+            "requested_fields": list(info_req.get("requested_fields") or []),
+            "questions": questions,
+            "amount_usd": info_req.get("amount_usd"),
+            "merchant_name": info_req.get("merchant_name"),
+            "payment_status": info_req.get("payment_status"),
+            "payment_error": info_req.get("payment_error"),
+            "expires_at": info_req.get("expires_at"),
+        }
+
+    events = ticket.get("events") or []
+    block_events = [e for e in events if e.get("type") == "block_on_user"]
+    if not block_events:
+        return {"kind": "block_on_user", "prompt": "Waiting for user input.", "sensitive": False}
+    payload = block_events[-1].get("payload") or {}
+    out: dict[str, Any] = {
+        "kind": "block_on_user",
+        "prompt": payload.get("prompt", "Waiting for user input."),
+        "field": payload.get("field"),
+        "sensitive": bool(payload.get("sensitive", False)),
+    }
+    # Surface the creds_required signals when present. The OA renders
+    # `credential_intake_url` as a clickable link so the user can store
+    # their credentials via the dedicated web form rather than pasting
+    # them through chat. `reason`, `site`, and `fields` give the OA
+    # enough context to write a helpful prompt around the link.
+    for key in ("reason", "site", "fields", "credential_intake_url"):
+        value = payload.get(key)
+        if value is not None:
+            out[key] = value
+    return out
+
+
+# --- Tools ------------------------------------------------------------
+
+
+@mcp.tool()
+async def actionlayer_start_task(
+    goal: str,
+    max_budget_usd: Optional[float] = None,
+    webhook_url: Optional[str] = None,
+    idempotency_key: Optional[str] = None,
+    target_url: Optional[str] = None,
+    use_my_credentials: Optional[bool] = None,
+) -> dict[str, Any]:
+    """Start a new ActionLayer task.
+
+    Args:
+        goal: A natural-language description of what to do. Examples:
+            "Send Alex at alex@x.com an email to set up a 30-min call"
+            "Book a table for 2 at Liholiho, Friday 7pm"
+            "Hire someone to assemble an IKEA Malm dresser this Saturday"
+        max_budget_usd: Optional spend cap. The flow refuses to commit
+            money beyond this.
+        webhook_url: Optional URL ActionLayer POSTs ticket events to.
+        idempotency_key: Optional caller-supplied retry key. If you call
+            this tool twice with the same key within 24h, you get the
+            same ticket back — safe across timeouts and retries.
+        target_url: Optional. The specific https:// page the task should
+            run on. If the user's request clearly implies a website you
+            know (e.g. "make a meme" -> imgflip.com, "order coffee" ->
+            doordash.com, a tracking number -> usps.com), pass that
+            site's URL here — you have the conversation context, so you
+            resolve the destination better than ActionLayer can. When
+            omitted, ActionLayer figures out the destination itself
+            (slower if it has to fall back to a web search).
+        use_my_credentials: Optional. Set True when the user explicitly
+            wants the task to run on their own personal account at the
+            target site (e.g. "send the email from MY Gmail"). Set False
+            to force an ActionLayer-owned account (the user's underlying
+            identity is irrelevant). Leave unset to let the action's
+            default policy decide. If True and the user has no saved
+            credentials for the target site, the response from
+            `actionlayer_get_task` will surface a `credential_intake_url`
+            in `next_action` — render it as a clickable link so the user
+            can store their credentials safely.
+
+    Returns the ticket as {ticket_id, state, ...}. State is initially
+    "pending"; poll actionlayer_get_task to watch it progress.
+    """
+    client = _get_client()
+    credentials_source: Optional[str] = None
+    if use_my_credentials is True:
+        credentials_source = "user"
+    elif use_my_credentials is False:
+        credentials_source = "service"
+    try:
+        ticket = await client.start_task(
+            goal=goal,
+            max_budget_usd=max_budget_usd,
+            webhook_url=webhook_url,
+            idempotency_key=idempotency_key,
+            target_url=target_url,
+            credentials_source=credentials_source,
+        )
+    except ApiError as e:
+        return {"error": str(e), "status": e.status}
+    return {
+        "ticket_id": ticket.get("id"),
+        "state": ticket.get("state"),
+        "goal": ticket.get("goal"),
+        "created_at": ticket.get("created_at"),
+    }
+
+
+@mcp.tool()
+async def actionlayer_get_task(ticket_id: str) -> dict[str, Any]:
+    """Read the current state of a ticket.
+
+    Poll this until `state` is one of: completed, failed, cancelled, or
+    blocked_on_user. While `state` is `pending` ActionLayer is working
+    on it — keep polling, you have nothing to do. If `blocked_on_user`,
+    the response includes a `next_action` object with the prompt the
+    human needs to answer.
+
+    Returns:
+        ticket_id, state, goal, flow, result (when completed),
+        error (when failed), reason (free-text summary on completed
+        / failed; null otherwise), recent_events (last 5),
+        next_action (when blocked_on_user).
+    """
+    client = _get_client()
+    try:
+        ticket = await client.get_task(ticket_id)
+    except ApiError as e:
+        return {"error": str(e), "status": e.status, "ticket_id": ticket_id}
+    return {
+        "ticket_id": ticket.get("id"),
+        "state": ticket.get("state"),
+        "goal": ticket.get("goal"),
+        "flow": ticket.get("flow"),
+        "result": ticket.get("result"),
+        "error": ticket.get("error"),
+        "reason": ticket.get("reason"),
+        "created_at": ticket.get("created_at"),
+        "completed_at": ticket.get("completed_at"),
+        "recent_events": _summarize_events(ticket.get("events") or []),
+        "next_action": _next_action(ticket),
+    }
+
+
+@mcp.tool()
+async def actionlayer_reply(
+    ticket_id: str,
+    message: Optional[str] = None,
+    field: Optional[str] = None,
+    value: Optional[str] = None,
+    sensitive: bool = False,
+    field_values: Optional[dict[str, str]] = None,
+    payment_approved: Optional[bool] = None,
+) -> dict[str, Any]:
+    """Resume a ticket that's waiting on the user.
+
+    Use this only when actionlayer_get_task returned state
+    "blocked_on_user". The `next_action` object on that response tells
+    you which shape to send.
+
+    TWO SHAPES, picked from next_action.kind:
+
+    1. STANDARD REPLY (next_action.kind == "block_on_user"): pass
+       `field` + `value` (and `sensitive=true` for secrets). This is
+       the common case — ActionLayer needs one piece of info
+       (date, address, 2FA code), ticket then goes back to EXECUTING.
+
+    2. INFO-REQUIRED REPLY (next_action.kind == "info_request"): pass
+       `field_values` as a dict {requested_field: user_value} whose
+       keys EXACTLY MATCH next_action.requested_fields ∪
+       {q.key for q in next_action.questions}.
+
+       PAYMENTS ARE APPROVED IN THE LINK APP, NEVER IN CHAT. When
+       next_action.amount_usd is set, branch on
+       next_action.payment_status:
+         - "wallet_required": the user has no Link wallet connected.
+           Tell them to connect one at the ActionLayer dashboard's
+           Connections page (they'll need the Link app on their
+           phone); DO NOT call actionlayer_reply yet. Once connected,
+           the ask proceeds automatically.
+         - "pending_info": collect the requested info and call
+           actionlayer_reply with `field_values`. The payment
+           approval request is sent to the user's Link app right
+           after — tell them to expect it there.
+         - "pending_wallet_approval": an approval request for $X is
+           waiting in the user's Link app RIGHT NOW (10-minute
+           window). Tell them to open Link and approve it there;
+           poll actionlayer_get_task to see it land.
+         - "approval_expired": the window lapsed. Call
+           actionlayer_reply with payment_approved=true to send a
+           fresh approval request to their Link app.
+       The user can decline at any point: payment_approved=false
+       fails the task (reason payment_rejected). No card data is
+       ever fetched or sent through this call.
+
+    SENSITIVE VALUES (passwords, 2FA codes): set `sensitive=true`.
+    Pass the value the user typed directly — DO NOT echo it into
+    other tool calls, agent thoughts, or messages. The API encrypts
+    it at rest, redacts it in logs, and purges it when the ticket
+    terminates.
+
+    Args:
+        ticket_id: The ticket waiting on the user.
+        message: Optional free-form note (non-secret). Lands on the
+            transcript as-is.
+        field: Standard reply — machine-readable key from
+            next_action.field.
+        value: Standard reply — the user's answer.
+        sensitive: Standard reply — True if value is a secret.
+        field_values: Info-required reply — {field: value} dict
+            matching next_action.requested_fields ∪ question keys
+            exactly.
+        payment_approved: Payment-ask control. False declines the
+            charge (ticket FAILS with reason payment_rejected). True
+            re-sends the approval push when payment_status is
+            "approval_expired". The approval itself always happens
+            in the user's Link app.
+    """
+    # Build the nested info payload when either flat info-required
+    # arg is present. The route 422s if the ticket carries an
+    # info_request but `info` is missing on the reply.
+    info: Optional[dict[str, Any]] = None
+    if field_values is not None or payment_approved is not None:
+        info = {}
+        if field_values is not None:
+            info["field_values"] = field_values
+        if payment_approved is not None:
+            info["payment_approved"] = payment_approved
+
+    client = _get_client()
+    try:
+        ticket = await client.reply_task(
+            ticket_id,
+            message=message,
+            field=field,
+            value=value,
+            sensitive=sensitive,
+            info=info,
+        )
+    except ApiError as e:
+        return {"error": str(e), "status": e.status, "ticket_id": ticket_id}
+    return {
+        "ticket_id": ticket.get("id"),
+        "state": ticket.get("state"),
+    }
+
+
+@mcp.tool()
+async def actionlayer_cancel(ticket_id: str) -> dict[str, Any]:
+    """Cancel a non-terminal ticket.
+
+    Idempotent on terminal states — calling cancel on a completed/
+    failed/already-cancelled ticket returns the ticket as-is.
+    """
+    client = _get_client()
+    try:
+        ticket = await client.cancel_task(ticket_id)
+    except ApiError as e:
+        return {"error": str(e), "status": e.status, "ticket_id": ticket_id}
+    return {
+        "ticket_id": ticket.get("id"),
+        "state": ticket.get("state"),
+    }
+
+
+@mcp.tool()
+async def actionlayer_submit_feedback(
+    ticket_id: str,
+    rating: str,
+    comment: Optional[str] = None,
+) -> dict[str, Any]:
+    """Leave feedback on a finished task.
+
+    Use after actionlayer_get_task shows state "completed" or "failed"
+    (the API rejects feedback on any other state). `rating` is "good"
+    or "bad"; `comment` is an optional free-text note. One feedback per
+    task — calling again overwrites the previous rating/note.
+    """
+    client = _get_client()
+    try:
+        result = await client.submit_feedback(
+            ticket_id, rating=rating, comment=comment
+        )
+    except ApiError as e:
+        return {"error": str(e), "status": e.status, "ticket_id": ticket_id}
+    return {
+        "ticket_id": result.get("ticket_id"),
+        "rating": result.get("rating"),
+        "ok": True,
+    }
+
+
+@mcp.tool()
+async def actionlayer_list_skills(
+    source_format: Optional[str] = None,
+) -> dict[str, Any]:
+    """List skills registered for this user.
+
+    Args:
+        source_format: Optional filter — "agentskills", "hermes",
+            "openclaw", "claude-code". Omit for all.
+
+    Returns {"skills": [{id, name, description, source_format, ...}, ...]}.
+    """
+    client = _get_client()
+    try:
+        skills = await client.list_skills(source_format=source_format)
+    except ApiError as e:
+        return {"error": str(e), "status": e.status, "skills": []}
+    return {
+        "skills": [
+            {
+                "id": s.get("id"),
+                "name": s.get("name"),
+                "description": s.get("description"),
+                "source_format": s.get("source_format"),
+                "lifecycle": s.get("lifecycle"),
+            }
+            for s in skills
+        ]
+    }
+
+
+# --- Action catalog tools (P10) --------------------------------------
+#
+# These expose the typed action surface. Agents that prefer structured
+# tool-use (vs. natural-language goals) should call these.
+#
+# Note: we surface the catalog as ONE generic tool
+# (actionlayer_invoke_action) parameterized by action_id, rather than
+# emitting 22+ separate MCP tools (gmail_send_email, gmail_summarize_inbox,
+# ...). Build doc §16 calls this out — "one connector covers all 30+
+# actions". The single-tool model matches Composio's surface and keeps
+# the agent host's tool-discovery cost flat as we add actions.
+
+
+# actionlayer_list_actions: prose capability sketch.
+#
+# History: this tool used to return a structured catalog of typed
+# action ids (resy.book_table, partiful.create_event, ...). Hosts
+# read that as the menu of what ActionLayer can do and presented it
+# as a fixed catalog, the opposite of the intent. Removing the tool
+# entirely (the 2026-05-30 morning fix) over-corrected — hosts then
+# got "Unknown tool" errors when they reached for a familiar name.
+#
+# Now: the tool exists and returns prose only. No typed ids, no
+# provider/category filters, no list shape. The body describes what
+# ActionLayer can do, gives concrete use-case examples woven through
+# as natural language, and points the host at actionlayer_start_task
+# or actionlayer_invoke_action(action_id='direct.browser_action').
+# Provider names appear inside example sentences but never as a list,
+# so the host can't read them as a fixed catalog.
+#
+# actionlayer_get_action stays removed (also 2026-05-30 morning):
+# there's no schema to fetch when typed ids are not advertised.
+#
+# Keep _CAPABILITY_SKETCH below in sync with the parallel constant
+# in actionlayer/mcp/remote.py.
+
+_CAPABILITY_SKETCH = (
+    "ActionLayer drives a real browser end-to-end to finish jobs on "
+    "any website. Most agents quit at the hard part — a CAPTCHA, a "
+    "novel checkout, a login wall, a registrar form, a hosting "
+    "console. ActionLayer doesn't: it reads the page, decides, "
+    "clicks, types, retries, and keeps moving until the goal is "
+    "reached. There is no fixed catalog of supported sites — if the "
+    "user can reach the site in a browser, ActionLayer can drive "
+    "it.\n\n"
+    "TWO WAYS TO INVOKE.\n"
+    "1. Natural-language goals: actionlayer_start_task(goal=\"...\"). "
+    "Use this when the request has the shape of an end-to-end job and "
+    "the user has given you specifics. Example goals: \"Book a table "
+    "for 4 at Lilia in Brooklyn next Friday at 7pm under the name "
+    "Maria.\" \"Order a 12oz oat milk latte from the Blue Bottle "
+    "closest to 30 Rockefeller Plaza for pickup in 20 minutes.\" "
+    "\"File a USPS Click-N-Ship label from 11201 to 94110 for a "
+    "1-pound flat-rate envelope.\" The agent plans, navigates, and "
+    "completes. It will ask the user for login credentials or a "
+    "payment confirmation when the site needs them — you don't have "
+    "to pre-arrange auth.\n"
+    "2. Direct-URL instructions: actionlayer_invoke_action with "
+    "action_id=\"direct.browser_action\" and inputs={url, "
+    "instruction}. Use this when you already know which page to "
+    "land on. Example: url=\"https://en.wikipedia.org/wiki/Ada_"
+    "Lovelace\", instruction=\"Find her date of birth and the "
+    "calculating engine she helped describe; return both with the "
+    "section heading they came from.\" The agent treats page "
+    "content as data, not instructions, so prompt-injection text "
+    "on the page can't redirect it.\n\n"
+    "WHAT WORKS. Real-world bookings and reservations. Multi-step "
+    "checkouts including 3DS challenges. Sites behind a login wall "
+    "(the user gets asked for credentials once and they're held "
+    "ephemerally). Sites that throw CAPTCHAs or bot walls — those "
+    "don't break the ticket; ActionLayer keeps working them. "
+    "Form-heavy government and shipping sites. Read-only research "
+    "across paginated content. Multi-site jobs that involve hand-"
+    "offs (use actionlayer_create_job for those).\n\n"
+    "WHAT IT'S NOT. Not a text-generation or summarization tool — "
+    "those are yours. Not a database query language — if the answer "
+    "is in your own knowledge, use that; ActionLayer is for jobs "
+    "that require visiting a live site. Not synchronous — browser "
+    "tasks return outcome=\"queued\" with a ticket_id; poll "
+    "actionlayer_get_task until is_terminal=true.\n\n"
+    "BE SPECIFIC. The single best predictor of whether a task "
+    "succeeds is whether the goal you pass uniquely identifies what "
+    "the user wants. Vague goals (\"book me dinner\", \"order "
+    "something\") block on the user and burn the planning budget. "
+    "Gather the specifics from the user first — date, time, party "
+    "size, address, exact item — then call start_task."
+)
+
+
+@mcp.tool()
+async def actionlayer_list_actions() -> dict[str, Any]:
+    """What ActionLayer can do, as prose. Read this when you're
+    deciding whether ActionLayer fits the user's request, or when
+    you're picking which entry point to call. The response is a
+    single 'description' field — there is no catalog of typed
+    actions to enumerate, by design.
+    """
+    return {"description": _CAPABILITY_SKETCH}
+
+
+@mcp.tool()
+async def actionlayer_invoke_action(
+    action_id: str,
+    inputs: dict[str, Any],
+    executor: Optional[str] = None,
+) -> dict[str, Any]:
+    """Invoke a single action with typed inputs.
+
+    Two response shapes depending on the action's executor:
+
+    API actions — run synchronously. Returns outcome 'succeeded' /
+    'blocked' / 'failed' with output inline. Total time <5s typical.
+
+    Browser actions — return outcome='queued' immediately with
+    payload.ticket_id. These run in the background (30s to several
+    minutes). DO NOT RETRY on queued — retrying double-charges the
+    browser session and creates duplicate work. Instead:
+
+      1. Read payload.ticket_id from the response.
+      2. Call actionlayer_get_action_ticket(ticket_id) every 5
+         seconds.
+      3. Stop polling when is_terminal=true. Final outcome is in
+         the same field shape as sync (succeeded / blocked / failed).
+      4. If outcome=='blocked', the ticket is waiting on the USER
+         to provide something (e.g. login credentials via the
+         creds_prompt field). Do NOT re-call
+         actionlayer_invoke_action — the ticket is still alive.
+
+    Args:
+        action_id: Action id from actionlayer_list_actions
+            (e.g. 'resy.book_table').
+        inputs: Typed inputs matching the action's input_schema.
+            Required fields and types are visible via
+            actionlayer_get_action. Extra fields are rejected (422).
+        executor: Optional 'api' or 'browser'. When unset, the
+            dispatcher picks the action's preferred kind.
+
+    Returns:
+        action_id, executor_used, outcome, output, error,
+        blocked_reason, cost_usd, payload
+        (payload always contains ticket_id; when outcome=='queued',
+        payload also contains poll_path).
+
+    Common error responses:
+        404 — action_id not in the catalog
+        412 — auth not connected for this action's provider (the
+            user needs to complete the browser login, or connect
+            OAuth where supported, before retrying)
+        422 — inputs failed input_schema validation
+    """
+    # Cap size + depth on the inputs dict before any network round
+    # trip. The Pydantic schema check happens server-side, but a
+    # multi-MB nested dict OOMs the API process during parse before
+    # the schema rejects it. SEC-MCP-012.
+    if _inputs_too_big(inputs):
+        return {
+            "error": (
+                "inputs payload exceeds size/depth cap "
+                "(64KB serialized or >10 nested levels)."
+            ),
+            "status": 422,
+            "action_id": action_id,
+        }
+
+    client = _get_client()
+    try:
+        return await client.invoke_action(
+            action_id, inputs=inputs, executor=executor
+        )
+    except ApiError as e:
+        return {"error": str(e), "status": e.status, "action_id": action_id}
+
+
+def _inputs_too_big(inputs: dict[str, Any]) -> bool:
+    """True if `inputs` exceeds the size or nesting cap.
+
+    Size cap is on the serialized JSON form so it scales with what
+    the server will see, not the in-memory Python footprint. Depth
+    cap is on nested dict/list structure so a deeply-nested DoS
+    can't blow the recursion budget.
+    """
+    import json as _json
+
+    try:
+        if len(_json.dumps(inputs, separators=(",", ":"))) > 64 * 1024:
+            return True
+    except (TypeError, ValueError):
+        return True
+
+    def _depth(value: Any, current: int = 0) -> int:
+        if current > 10:
+            return current
+        if isinstance(value, dict):
+            return max(
+                (_depth(v, current + 1) for v in value.values()),
+                default=current,
+            )
+        if isinstance(value, list):
+            return max(
+                (_depth(v, current + 1) for v in value),
+                default=current,
+            )
+        return current
+
+    return _depth(inputs) > 10
+
+
+@mcp.tool()
+async def actionlayer_get_action_ticket(ticket_id: str) -> dict[str, Any]:
+    """Poll an action ticket for its current state.
+
+    Use after actionlayer_invoke_action returns outcome='queued'.
+    Recommended cadence: 5 seconds between polls (browser actions
+    typically take 30s-5min; faster polling just wastes calls).
+
+    Stop polling when is_terminal=true. At that point:
+      * outcome=='succeeded' — output contains the typed result;
+        `reason` carries a free-text summary when one is available.
+      * outcome=='blocked' — ActionLayer is waiting on the user to
+        provide something (e.g. login credentials via creds_prompt,
+        or a value via the standard reply flow). blocked_reason
+        names the ask ('creds_required' = login credentials).
+        Stop polling here and surface the prompt to the user.
+      * outcome=='failed' — `error` / `reason` explain why.
+
+    While outcome is None and is_terminal=false the ticket is in
+    `pending` — ActionLayer is still working on it; keep polling.
+    There is no sub-status to interpret.
+
+    Args:
+        ticket_id: from payload.ticket_id of the original
+            actionlayer_invoke_action response.
+
+    Returns:
+        ticket_id, action_id, state, outcome, output, error, reason,
+        blocked_reason, is_terminal
+    """
+    client = _get_client()
+    try:
+        return await client.get_action_ticket(ticket_id)
+    except ApiError as e:
+        return {"error": str(e), "status": e.status, "ticket_id": ticket_id}
+
+
+# --- Credential tools (per-task auth) ---------------------------------
+#
+# Browser actions that hit a login wall pause the ticket in
+# blocked_on_user with a creds_required prompt. The user (or the LLM
+# reading host secrets) provides credentials via
+# actionlayer_provide_credentials. The worker injects them into the
+# in-flight browser session for that ONE execution, then wipes
+# the values. Never persisted to disk.
+#
+# Optional same-session reuse (remember_for_session=true) keeps the
+# creds in Redis with a 1-hour TTL keyed by (user, site). Wiped on
+# job completion or TTL expiry.
+
+
+@mcp.tool()
+async def actionlayer_provide_credentials(
+    ticket_id: str,
+    fields: dict[str, str],
+    remember_for_session: bool = False,
+) -> dict[str, Any]:
+    """Submit credentials for an action ticket blocked with creds_required.
+
+    Use this AFTER actionlayer_get_action_ticket shows a creds_prompt
+    in the response (state=blocked_on_user, blocked_reason=user,
+    creds_prompt.reason='creds_required'). The prompt's `fields`
+    list tells you what keys to send.
+
+    Credentials are encrypted in transit, stored in Redis with a
+    15-minute TTL, popped atomically by the worker (single-use), and
+    wiped from in-process memory after the agent loop returns. They
+    are NEVER written to Postgres or any persistent log.
+
+    Args:
+        ticket_id: From the original action invocation.
+        fields: Dict mapping each field name from creds_prompt.fields
+            to its value (e.g. {"email": "...", "password": "..."}).
+        remember_for_session: If True, ALSO keep an encrypted copy
+            in Redis for 1 hour, scoped to (this user, this site).
+            Subsequent blocks for the SAME site during the same agent
+            session auto-resolve without re-prompting. Default False.
+
+    Returns:
+        {ticket_id, state, status} — state transitions to "executing".
+        The agent resumes within ~5s.
+        Poll actionlayer_get_action_ticket again to see the next state.
+
+    IMPORTANT: Do NOT echo credentials back to the user after this
+    call succeeds. They are now in transit to the worker — confirming
+    receipt is enough.
+    """
+    client = _get_client()
+    try:
+        return await client.provide_credentials(
+            ticket_id,
+            fields=fields,
+            remember_for_session=remember_for_session,
+        )
+    except ApiError as e:
+        return {"error": str(e), "status": e.status, "ticket_id": ticket_id}
+
+
+@mcp.tool()
+async def actionlayer_read_host_secret(slot_name: str) -> dict[str, Any]:
+    """Read a credential slot from the agent host's environment.
+
+    This lets the LLM check if the user has pre-configured a secret
+    (e.g. RESY_PASSWORD, GMAIL_PASSWORD) in their Claude Code env
+    BEFORE prompting them. Reads `os.environ[slot_name]` in the MCP
+    server process — the secret never travels to ActionLayer's
+    backend unless the LLM then passes it to
+    actionlayer_provide_credentials.
+
+    Recommended slot naming: `<SITE>_<FIELD>`, all caps, no spaces.
+        RESY_EMAIL, RESY_PASSWORD
+        GMAIL_EMAIL, GMAIL_PASSWORD
+        GITHUB_USERNAME, GITHUB_PASSWORD
+
+    Args:
+        slot_name: env var name to look up.
+
+    Returns:
+        {found: bool, value?: str}
+        When found=False, no value is set in the response — the LLM
+        should fall back to asking the user.
+
+    Security:
+        * The slot name is validated (uppercase + underscores only)
+          to prevent process-env exfiltration via slot_name='PATH'
+          etc.
+        * The MCP server logs slot_name but NEVER the value.
+        * Returning the value to the LLM means it enters the model
+          context. The user opting to set the env var is their
+          explicit consent to that.
+    """
+    # Validate slot name: only allow A-Z, 0-9, underscore. Refuse
+    # anything that could read sensitive process env like PATH, HOME,
+    # LD_PRELOAD, etc. — accidentally readable but not via this tool.
+    import re
+
+    if not re.fullmatch(r"[A-Z][A-Z0-9_]*", slot_name or ""):
+        return {
+            "found": False,
+            "error": (
+                f"Invalid slot name {slot_name!r}. Use uppercase "
+                "letters, digits, and underscores only — e.g. "
+                "'RESY_PASSWORD'."
+            ),
+        }
+    value = os.environ.get(slot_name)
+    if not value:
+        return {"found": False}
+    return {"found": True, "value": value}
+
+
+# --- Job tools (P10) -------------------------------------------------
+#
+# Jobs are for multi-step plans. Single actions stay on
+# actionlayer_invoke_action (sync). Jobs are async — caller polls
+# actionlayer_get_job until terminal.
+
+
+@mcp.tool()
+async def actionlayer_create_job(
+    goal: str,
+    budget_usd: Optional[float] = None,
+    deadline: Optional[str] = None,
+    webhook_url: Optional[str] = None,
+) -> dict[str, Any]:
+    """Create a multi-step job from a natural-language goal.
+
+    The planner (Claude Sonnet 4.6) decomposes the goal into N
+    ordered actions, possibly with output piping between them.
+    Examples:
+        "Find a 30-min slot next week, then email alex@x.com to
+         schedule it"
+        "Summarize my unread emails, then post the count to
+         Slack #general"
+
+    Returns the job in 'planning' state. Poll actionlayer_get_job
+    until state is one of: complete, partial, failed, cancelled,
+    blocked.
+
+    Use actionlayer_invoke_action for single-action goals — it's
+    sync and skips the planner round-trip.
+
+    Args:
+        goal: Natural-language description of the work.
+        budget_usd: Optional total spend cap.
+        deadline: Optional ISO 8601 deadline (e.g.
+            '2026-05-15T19:00:00-07:00'). Planner picks faster
+            actions when deadlines are tight.
+        webhook_url: HTTPS URL POSTed on terminal state. Optional.
+
+    Returns the Job row: {id, goal, state, plan, budget_usd, ...}.
+    """
+    client = _get_client()
+    body: dict[str, Any] = {"goal": goal}
+    if budget_usd is not None:
+        body["budget_usd"] = budget_usd
+    if deadline is not None:
+        body["deadline"] = deadline
+    if webhook_url is not None:
+        body["webhook_url"] = webhook_url
+    try:
+        return await client.create_job(
+            goal=goal,
+            budget_usd=budget_usd,
+            deadline=deadline,
+            webhook_url=webhook_url,
+        )
+    except ApiError as e:
+        return {"error": str(e), "status": e.status}
+
+
+@mcp.tool()
+async def actionlayer_get_job(job_id: str) -> dict[str, Any]:
+    """Read a job's current state + per-step items.
+
+    Terminal states: complete, partial, failed, cancelled. Non-terminal:
+    planning, executing, blocked.
+
+    `items` is the list of plan steps; each has its own state,
+    inputs, result, and (if blocked) the reason.
+
+    Returns the Job row with `items` populated.
+    """
+    client = _get_client()
+    try:
+        return await client.get_job(job_id)
+    except ApiError as e:
+        return {"error": str(e), "status": e.status, "job_id": job_id}
+
+
+@mcp.tool()
+async def actionlayer_cancel_job(job_id: str) -> dict[str, Any]:
+    """Cancel an in-flight job. Idempotent on terminal states.
+
+    Note: cancellation is cooperative-on-fetch — if a job is
+    mid-step when this is called, the current step finishes before
+    the job transitions to cancelled.
+    """
+    client = _get_client()
+    try:
+        return await client.cancel_job(job_id)
+    except ApiError as e:
+        return {"error": str(e), "status": e.status, "job_id": job_id}
+
+
+@mcp.tool()
+async def actionlayer_resume_job(job_id: str) -> dict[str, Any]:
+    """Resume a job that's in 'blocked' state.
+
+    Use after the user has resolved the blocker (e.g. replied with
+    a 2FA code via actionlayer_reply, or provided credentials).
+    The worker re-evaluates the plan and continues from where it
+    paused.
+
+    Returns 409 if the job isn't in 'blocked' state.
+    """
+    client = _get_client()
+    try:
+        return await client.resume_job(job_id)
+    except ApiError as e:
+        return {"error": str(e), "status": e.status, "job_id": job_id}
+
+
+# --- Configure subcommand --------------------------------------------
+
+
+def _configure(api_key: str, api_url: Optional[str]) -> None:
+    """Write a basic Claude Desktop / Claude Code MCP config snippet to stdout.
+
+    Doesn't auto-edit the user's config file — printing keeps the action
+    visible and lets the user paste into whichever host they use.
+    """
+    snippet = {
+        "mcpServers": {
+            "actionlayer": {
+                "command": "uvx",
+                "args": ["actionlayer"],
+                "env": {
+                    "ACTIONLAYER_API_KEY": api_key,
+                    **({"ACTIONLAYER_API_URL": api_url} if api_url else {}),
+                },
+            }
+        }
+    }
+    print("Add this to your MCP host config (Claude Desktop, Cursor, etc.):\n")
+    print(json.dumps(snippet, indent=2))
+    print()
+    home_hint = Path.home() / "Library/Application Support/Claude/claude_desktop_config.json"
+    if sys.platform == "darwin":
+        print(f"On macOS, Claude Desktop config lives at:\n    {home_hint}")
+
+
+# --- Entry point -----------------------------------------------------
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="actionlayer",
+        description="ActionLayer MCP server (Model Context Protocol).",
+    )
+    sub = parser.add_subparsers(dest="cmd")
+
+    cfg = sub.add_parser(
+        "configure",
+        help="Print MCP host config snippet for a given API key.",
+    )
+    cfg.add_argument("--api-key", required=True)
+    cfg.add_argument("--api-url", default=None)
+
+    args = parser.parse_args()
+
+    if args.cmd == "configure":
+        _configure(args.api_key, args.api_url)
+        return
+
+    # Default: run the MCP server over stdio. The host (Claude Code,
+    # Cursor, etc.) launches us with stdin/stdout connected and speaks
+    # MCP JSON-RPC. fastmcp.run() blocks until the host disconnects.
+    if not os.environ.get("ACTIONLAYER_API_KEY"):
+        print(
+            "ACTIONLAYER_API_KEY env var is not set. Either set it in your "
+            "MCP host config (recommended) or run "
+            "`actionlayer configure --api-key ak_...` for setup help.",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+
+    try:
+        asyncio.run(mcp.run_async())
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    main()