managed-deepagents 0.10.0-dev.17 → 0.10.0-dev.19

package/README.md

@@ -151,7 +151,7 @@ strings and arrays remain explicit selections. Select memory with `defineMemory(
 selected memory cannot use `allow`. Root `memory.ts` remains the fallback.
 
 On direct runs, `executionRuntime.context` is application context or `undefined`.
-On channel runs, it is `undefined`; read delivery data from `runtime.channel`.
+On channel runs, it is `undefined`; read the conversation from `runtime.thread`.
 `ManagedServerRuntime<AppContext>` preserves the application's context type.
 `accessContext` identifies the Agent Server operation that called the factory.
 During inspection, `executionRuntime` is `null`. Keep the factory repeatable and
@@ -243,12 +243,18 @@ current channel delivery:
 runtime
   .context          // Application data on direct runs
   .serverInfo       // Trusted caller and server information
-  .channel          // Present for a managed channel delivery
-    .name           // Configured channel name
-    .provider       // Provider label, such as slack
-    .event          // Typed MDA delivery; no internal routing
-    .rawEvent       // Optional original provider payload
-    .post(...)      // Present when sending is supported
+  .thread           // The run's thread
+    .id             // LangGraph thread ID
+    .origin         // The channel conversation, or null
+      .channel      // Where answers go
+        .name       // Configured channel name
+        .provider   // Provider label, such as slack
+        .event      // Typed MDA delivery, or null
+        .rawEvent   // Optional original provider payload
+        .post(...)  // Present when sending is supported
+      .sender       // The participant who sent the latest event, or null
+    .participants   // The people on the thread: { id, role }
+  .channel          // Deprecated: runtime.thread.origin?.channel
   .backend          // Present when a sandbox is configured
   .schedules        // Create and manage schedules for this run's caller
 ```
@@ -265,8 +271,8 @@ await client.runs.create(threadId, assistantId, {
 Direct API runs use your authored `contextSchema` and native LangGraph context
 validation. On channel runs, tools and authored factories receive `undefined`
 as context. Native middleware receives an empty context. Use
-`runtime.channel.event` for the typed event and `runtime.channel.rawEvent` for
-optional provider data. The application schema stays on the graph, but its
+`runtime.thread.origin.channel.event` for the typed event and
+`runtime.thread.origin.channel.rawEvent` for optional provider data. The application schema stays on the graph, but its
 required fields do not apply to channel runs. Supplying a `channel` field in a
 direct API call does not establish a trusted channel source.
 
@@ -277,28 +283,63 @@ in the graph factory for each run or resume. Direct callers of the managed
 compiler must build a fresh graph with the execution's context; a compiled graph
 is scoped to that execution.
 
-`runtime.channel` describes the current verified delivery. It is absent on
-ordinary API and schedule runs. Its facts are available even when the channel
-cannot send. `post` uses a private, verified reply target. The channel helper
-does not expose the target or let callers replace it.
+`runtime.thread` is set in every run. `origin` is the channel conversation the
+thread came from; it is `null` on a thread no channel message reached. Managed
+ingress records the origin on the thread on every channel message, so runs that
+no message started still have it: a run LangSmith Studio resumes, and a
+scheduled run on the thread. In those runs `origin.channel.event` is `null` (a
+scheduled run gets a `schedule` event) and there is no `rawEvent`. The channel's
+facts are available even when it cannot send. `post` uses a private, verified
+reply target. The channel helper does not expose the target or let callers
+replace it.
 
 ```ts
-if (runtime.channel?.post) {
-  await runtime.channel.post({
+const channel = runtime.thread?.origin?.channel;
+if (channel?.post) {
+  await channel.post({
     type: "content",
     content: "I am checking that now.",
   });
 }
 ```
 
-The built-in Slack `runtime.channel.post` sends text content through Trigger.
+`participants` lists the people on the thread, in the order they joined, by
+`principal.id` (the same id as `runtime.serverInfo.principal.id`). The first
+person is `owner`; everyone after is a `member`. Services, such as the Linear
+channel, are never participants. `origin.sender` is the participant who sent the
+latest channel event, or `null` when that was not a person. The record holds
+ids and routing only, never message text or provider payloads, because thread
+metadata reaches traces.
+
+`runtime.channel` is deprecated and will be removed in 0.11. It is the same
+value as `runtime.thread.origin?.channel`.
+
+When a run ends, MDA posts its answer to the thread's origin: Slack through
+Trigger, HTTP channels through their `post`. A run that stops on an interrupt
+reports it to Trigger, so Slack can ask for the decision. Answer `[quiet]` to
+post nothing.
+
+The built-in Slack channel `post` sends text content through Trigger.
 It rejects native payloads and content it cannot send. For channels that support
 native messages, set `type` to `"native"` and supply the JSON in `native`.
 For content messages, set `type` to `"content"` and supply `content`.
 Supply only the matching payload. Native JSON has no extra provider or payload
-wrapper. The `runtime.channel` helper has no `address`, `update`, or destination override.
+wrapper. The channel helper has no `address`, `update`, or destination override.
 A post sends an additional message; the normal final agent reply remains automatic.
 
+On Slack, `post(message, { newThread: true })` posts at top level in the same
+conversation instead, which starts a new Slack thread. Replies in it continue a
+thread of their own, also without a mention in thread mode. Add `run` to start a
+run there at once, with a channel handler's run input, as the current run's
+person. The result also has `threadId` and, on Slack, the message `url`:
+
+```ts
+const posted = await runtime.thread?.origin?.channel.post?.(
+  { type: "content", content: "Haiku about mango" },
+  { newThread: true, run: { messages: [...history, new HumanMessage("Go on.")] } }
+);
+```
+
 Managed Slack channels save incoming files under `/workspace/attachments/` and
 add `upload_files(paths)` so the agent can attach completed workspace files
 to its reply. This requires a managed sandbox.
@@ -318,7 +359,8 @@ MDA does not reuse the previous delivery's event.
 For a prompt that answers an interrupt, put a shared ID on the prompt and on the
 interrupt value under `INTERRUPT_CORRELATION_KEY`. MDA uses `correlation_id` to
 select that interrupt. Without a correlation ID, an answer can resume the only
-pending interrupt; multiple pending interrupts require a match. Existing resume
+pending interrupt that isn't a tool-call review; multiple pending interrupts
+require a match. Existing resume
 values are unchanged.
 
 The managed runtime fields are available to authored tools and middleware,
@@ -339,6 +381,312 @@ alias for the tool type. MDA adds `serverInfo`, `channel`, `backend`, and
 but the type marks it optional so annotated hooks still match LangChain's native
 runtime types.
 
+## Slack channels
+
+`channels.slack(...)` receives Slack messages through Trigger Server. Each
+Slack thread is one conversation, and the run's reply is posted in it. By
+default every message that reaches the app starts a run with the message.
+`onEvent` decides what each kind of message starts instead:
+
+```ts
+// channels/slack.ts
+import { channels } from "managed-deepagents";
+
+export const channel = channels.slack({
+  name: "Support Bot",
+  triggerMode: "thread",
+  onEvent: {
+    mention: (event, thread) => [
+      event.text,
+      {
+        context: { ticket: thread.id },
+        metadata: { slack_channel: event.channelId },
+      },
+    ],
+    directMessage: (event) => event.text,
+    // Replies in a followed thread that don't mention the app start nothing.
+    message: () => null,
+  },
+  multitaskStrategy: "enqueue",
+});
+```
+
+The keys are `mention`, a channel message that @-mentions the app;
+`directMessage`; and `message`, any other channel message, which only
+`triggerMode` `"thread"` or `"all"` delivers. Under those modes Slack sends a
+mention as a plain message, so the channel asks Slack once for the app's bot
+user, with the app's bot token, to tell a mention from a message. An unknown
+key throws. A message kind without a handler starts a run with the message,
+as without `onEvent`. With `triggerMode: "mention"`, a `message` handler is
+never called, and defining the channel warns.
+
+With a `mention` handler under `triggerMode` `"thread"`, a reply only
+continues a thread the agent already ran on: when the handler declines a
+thread's mention, the thread's later replies start nothing until someone
+mentions the agent there again.
+
+A handler gets the message (`text`, `userId`, `channelId`, `messageTs`,
+`threadTs`, `files`, Slack's own event as `payload`, and `actor`) and its
+thread (`id`, `sourceThreadKey`, `channel.name`). It returns the run's input, as
+`agent.invoke` takes it, optionally with `context`, `metadata` and `webhook`
+as `[input, options]`, as the GitHub and Linear handlers do. `null` or
+`undefined` starts no run, and the app neither reacts nor replies. A handler
+that throws, or returns input the channel can't start, starts no run either;
+the error is logged without its message. The message's blocks and attachments
+are added to the handler's messages, and its files still reach
+`/workspace/attachments/`. Interrupt resumes don't go through `onEvent`; a
+click on a button the agent posted does, as `interaction`: see
+[Buttons your agent posts](#buttons-your-agent-posts).
+
+A handler may also be an endpoint of your service, a URL or a `Request`:
+Trigger Server gets its answer first, then MDA asks the service what the
+message starts. See [Asking your service what to start](#asking-your-service-what-to-start).
+
+```ts
+const backend = new Request(`${process.env.BACKEND_URL}/slack/runs`, {
+  headers: { "x-api-key": process.env.BACKEND_KEY! },
+});
+
+export const channel = channels.slack({
+  onEvent: { mention: backend, directMessage: backend },
+});
+```
+
+`multitaskStrategy` is what a message that starts a run does while its thread
+already runs: `enqueue` (the default) waits for the run and starts after it,
+`interrupt` cancels the run, keeping its progress, and starts at once,
+`rollback` cancels it and discards its progress, and `reject` starts nothing.
+
+`event.actor` is the Slack user who sent the message, as Trigger Server read
+it from Slack's signed request: `{ provider: "slack", id, teamId }`. `teamId`
+is their own workspace: in a Slack Connect channel, someone from another
+organization keeps theirs. It is absent rather than guessed when Trigger
+Server names no one, such as an older Trigger Server or a bot's message.
+
+> **Not yet an identity check.** Trigger Server sends `actor` as a plain
+> field of the delivery, and MDA doesn't yet verify the key that delivery
+> comes with, only that it has one. Use `actor` to address or describe the
+> sender, not to decide what they may do or which of your accounts they are.
+
+Every channel's events carry `actor` in this shape, a `ChannelActor`: `{
+provider, id }` plus the provider's own fields. GitHub's is the webhook's
+`sender` (`name` is its login, plus `type` and `email?`), and Linear's is who
+acted (plus `type?`, `name?` and `email?`); Slack's has no name or email,
+since Trigger Server's delivery names none. Endpoints get it as `event.actor` too. It is personal
+data: MDA doesn't log it or add it to a run's metadata; add what you need
+through `metadata` yourself.
+
+`onFinish` is called once when a message or an `interaction` is done, with
+the event, its thread, and how it finished, as Linear's `onFinish` is:
+
+- `run`: the message started a run, which ended with `run.status`
+  (`success`, `error`, `timeout` or `interrupted`). `interrupts` lists the
+  decisions the thread waits on.
+- `skipped`: no run started. The handler returned nothing or failed
+  (`ignored`), or the thread was busy under `multitaskStrategy: "reject"`
+  (`rejected`).
+- `failed`: MDA couldn't start the run, or lost track of it.
+
+Use it to record which run answered which message in your own service,
+update memory after a run succeeds, or alert someone when one fails:
+
+```ts
+channels.slack({
+  onFinish: async (event, thread, finished) => {
+    if (finished.type !== "run") return;
+    if (finished.run.status === "success") {
+      // e.g. record the answer in your service, or update memory
+    } else {
+      // e.g. alert someone that the run failed
+    }
+  },
+});
+```
+
+It runs in the background after the reply, and errors are logged. Interrupt
+resumes don't call it, and neither does a message Trigger Server will send
+again because its run couldn't start. Like `channels.http`'s, it runs in the deployment's
+process, so a restart loses it: set the run's `webhook` for anything you
+can't miss.
+
+### The status a run shows
+
+While a run works, Slack shows Trigger Server's working phrases ("is thinking
+it through...", "reviewing your question..."). `status` shows yours instead,
+the way `reactions` picks the emoji: a value for every run, or a function that
+picks one. A value is a line, or a list of steps, each a title or `{ title,
+status }` with `status` `pending` (the default), `in_progress`, `complete` or
+`error`:
+
+```ts
+channels.slack({ status: "is consulting the crystal ball" });
+channels.slack({ status: ["Read the question", "Search the docs", "Answer"] });
+channels.slack({
+  // The agent's to-do list, as Slack's plan.
+  status: ({ state }) =>
+    state.todos?.map((todo) => ({
+      title: todo.content,
+      status: todo.status === "completed" ? "complete" : todo.status,
+    })) ?? null,
+});
+```
+
+The function gets the agent's state as it is now, so it can say which tool is
+about to run (the last message's `tool_calls`) or what's left on the to-do
+list. It is called as the run starts, before and after each model call, and
+every 4 s while a model or tool call runs, one call at a time. `null`, or an
+empty list (as a to-do list is before the agent writes one), leaves what's
+shown. A function that throws, takes longer than 1 s, or returns
+something else leaves it too, with one warning per run. The status is only
+posted when it changed, at most once a second, in the background, so it never
+slows the run; a failed post is logged. A sync function runs on the event
+loop, so do slow work in an async one.
+
+Apps with Slack's agent view show a custom status as a plan above the reply:
+the line is the plan's title and each step one of its tasks. A step that's
+no longer listed is marked complete, since Slack can't remove one, and the
+plan reads "Done" when the run ends. Other apps show the line, or the first
+step not yet done, as the thread's status. Without `status`, nothing changes.
+
+### Replying from the agent
+
+The channel posts the agent's last reply in the thread once a run succeeds.
+`reply: "none"` leaves replying to the agent instead, for an agent that posts
+its own messages, with `runtime.channel.post` or its own Slack client, or
+that answers somewhere else:
+
+```ts
+channels.slack({ reply: "none" });
+```
+
+Reactions, the status, Stop and `onFinish` work as before. `channels.linear`
+and `channels.http` take the same option. Deploying `reply: "none"` needs an
+`mda` CLI from this release; an older one refuses it.
+
+### Buttons your agent posts
+
+`runtime.channel.post` only sends what every channel can. For anything
+Slack-specific, such as buttons, feedback buttons or a message the agent
+updates later, the agent posts with its own Slack client. The app's bot token
+is the agent connection `mda/slack-bot-token` (reading it as a user connection
+throws), and `runtime.channel.rawEvent`, the Slack event the run came from,
+names the thread: a message's own event, or a click's interaction payload,
+whose `container` says where the button was.
+
+```ts
+import { WebClient } from "@slack/web-api";
+import { tool } from "langchain";
+import { z } from "zod";
+import { connections, type ManagedToolRuntime } from "managed-deepagents";
+
+export const offerChoices = tool(
+  async ({ question, choices }, runtime: ManagedToolRuntime) => {
+    if (runtime.channel?.provider !== "slack") return "Not in Slack.";
+    const raw = runtime.channel.rawEvent as Record<string, any> | undefined;
+    const where = raw?.container ?? raw;
+    const channel = where?.channel_id ?? where?.channel;
+    const threadTs = where?.thread_ts ?? where?.message_ts ?? where?.ts;
+    const token = await connections.get("mda/slack-bot-token", { type: "agent" });
+    await new WebClient(token).chat.postMessage({
+      channel,
+      thread_ts: threadTs,
+      text: question,
+      blocks: [
+        { type: "section", text: { type: "mrkdwn", text: question } },
+        {
+          type: "actions",
+          elements: choices.map((choice) => ({
+            type: "button",
+            action_id: "quick_reply",
+            text: { type: "plain_text", text: choice },
+            value: choice,
+          })),
+        },
+      ],
+    });
+    return "Posted the choices.";
+  },
+  {
+    name: "offer_choices",
+    description: "Ask the user to pick one of a few answers in Slack.",
+    schema: z.object({ question: z.string(), choices: z.array(z.string()) }),
+  }
+);
+```
+
+Trigger Server forwards a click on such a button to the channel. `onEvent`'s
+`interaction` decides what it starts, as the other keys do for messages:
+
+```ts
+channels.slack({
+  onEvent: {
+    interaction: (event) =>
+      event.actionId === "quick_reply" ? String(event.value) : null,
+  },
+});
+```
+
+The event has `actionId` (the button's `action_id`, or a modal's
+`callback_id`), `value` (the button's `value`, or the modal's `state.values`),
+`userId`, `channelId`, `messageTs` (the message holding the button; absent for
+a modal), `threadTs`, `actor`, and Slack's interaction payload as `payload`,
+with its `response_url` and without its verification `token`. The run it
+starts runs on the button's thread. Return `null` for a click that starts
+nothing, such as a `feedback_buttons` rating you record yourself. An endpoint works here too, as
+does `multitaskStrategy`.
+
+Without `interaction`, a click starts a run with no new message, which reads
+the click from `runtime.channel.event` (`type: "user_prompt_response"`, with
+`action` and `value`). A click that answers a decision the thread waits on
+resumes that run instead, and never reaches `interaction`. A click without a
+correlation ID never answers a tool-call review, which its own prompt answers:
+while the thread waits on one, such a click starts nothing. Trigger Server
+forwards clicks on buttons without a URL and on Slack's `feedback_buttons`;
+selects and inputs aren't forwarded.
+
+### Setting up the Slack app
+
+The first `mda deploy` of a Slack channel asks which Slack app it uses, as the
+GitHub and Linear channels do:
+
+- **Create a new Slack app in _your workspace_**: LangSmith creates and manages
+  it, in the workspace you authorized LangSmith in. Deploy names the workspace.
+- **Let LangSmith create and manage a new Slack app**: the same, when you
+  haven't authorized LangSmith in Slack yet. Deploy prints the link to do that.
+- **Create a new Slack app yourself**: Slack opens with the app filled in from
+  a manifest. Install it, then paste its Bot User OAuth Token and Signing
+  Secret into the prompts.
+- **Use an existing Slack app**: deploy lists the request URLs, bot events and
+  scopes to set on the app, then asks for its token and signing secret. Slack
+  sends an app's events to one URL, so whatever received them before stops
+  receiving them.
+
+Self-hosted LangSmith can't create Slack apps, so it offers only your own.
+LangSmith keeps the app's credentials, and later deploys keep whichever app
+the channel has without asking. The agent reads the app's bot token as the
+agent connection `mda/slack-bot-token`, so nothing goes into `.env`.
+
+To skip the question, with or without a terminal, set `MDA_SLACK_BOT_TOKEN`
+and `MDA_SLACK_SIGNING_SECRET` in the shell or `.env` to your own app's bot
+token and signing secret. Deploy checks them before uploading. Only the CLI
+reads them: they are never uploaded to the deployment, and you can remove both
+once the channel is set up. Without a terminal and without them, hosted
+LangSmith creates a managed app in the workspace you already authorized it in,
+and says so. When you haven't authorized it yet, or on self-hosted LangSmith,
+deploy stops before uploading and says what to set.
+
+When Slack still needs you once the deployment is live, to authorize LangSmith
+or to install the new app (some workspaces have an admin approve it first),
+deploy prints the link and waits, continuing as soon as Slack reports it done.
+In a terminal the link also opens in your browser, and Ctrl-C skips the
+channel. Without one, deploy waits up to an hour, so a coding agent running it
+can hand you the link; Ctrl-C stops it.
+
+If a setup step fails once the deployment is live, deploy offers to try again
+or to continue without the Slack channel. Without a terminal the failure ends
+the deploy, once the other channels are set up. An agent with a Slack channel
+can't be deployed with `--no-wait`, because setup needs the live deployment.
+
 ## GitHub channels
 
 The GitHub channel is a thin HTTP adapter. Add a channel file with event handlers:
@@ -375,26 +723,8 @@ Supabase or another provider. So MCP servers and tools that act on a user's
 behalf or need a user connection are left out of those runs, with a warning,
 and the run goes on without them. An issue or pull request is a shared
 conversation, so the sender gets user memory only where the user memory
-layer's `allow` opts in.
-The first deploy asks which GitHub account should own the App. Without a
-terminal, for example when a coding agent deploys, set `MDA_GITHUB_APP_OWNER` in
-the shell or `.env` to that organization, or to `@me` for the personal account
-of whoever creates the App. Deploy checks this before creating the deployment
-and fails without it. During setup it prints the link for a person to open and
-waits up to an hour for them to finish.
-To use an existing App instead, choose it on the first deploy and enter its App
-ID, private key file, installation ID and webhook secret. Agent Auth keeps them
-like a created App's, and deploy looks up the bot ID, so nothing goes into
-`.env`. `GH_WEBHOOK_SECRET` and `GH_APP_BOT_ID` (the App bot account's numeric
-user ID) still override the stored values. An App has one webhook URL: if the
-existing App's webhook points somewhere else, deploy asks before moving it to
-the deployment, and fails without a terminal. Answer "No" to keep it there, for
-example when another service receives the App's events and forwards the ones
-for this agent to `<deployment-url>/channels/github/events` with the body and
-GitHub's headers unchanged. Deploy remembers that URL and doesn't ask again, with
-or without a terminal, until the App's webhook moves. Without a terminal, set
-`MDA_GITHUB_WEBHOOK_ELSEWHERE` to the URL instead. If the App's installation
-lacks a permission the channel needs, deploy names it.
+layer's `allow` opts in. See [Setting up the GitHub App](#setting-up-the-github-app)
+for what the first deploy asks.
 
 Pass `app` to narrow what the agent can reach. Deploy applies changes to it on
 every run:
@@ -425,8 +755,6 @@ manifest only when the App is created, so the App's owner grants added
 permissions, and removes dropped or lowered ones, in the App's settings. Deploy
 names both and links there. `mda delete` removes the App's connections
 from Agent Auth and links the App on GitHub, where its owner can delete it.
-A new App is named after the agent, and the first deploy asks which account to
-create it in.
 The `GH_*` overrides are read at request time; the webhook secret and bot ID read
 from Agent Auth are cached for up to 5 minutes. A matched event fails closed if
 the bot ID is missing or invalid. Calling `channels.github()` without handlers preserves
@@ -571,17 +899,68 @@ Callbacks receive a normalized event and its `thread` (`thread.id`,
 `thread.channel.name`, and `thread.interrupted` while it waits on an interrupt). The event includes
 the original payload, delivery and installation IDs, repository and sender.
 Types describe handwritten subsets, not the complete GitHub schema. Run code can
-inspect the normalized event through `runtime.channel.rawEvent`. Logs correlate the GitHub
+inspect the normalized event through `runtime.thread.origin.channel.rawEvent`. Logs correlate the GitHub
 delivery ID to the fresh thread and run IDs without printing the payload.
 `GitHub handler returned run input` records the callback decision;
 `channel run started` confirms run creation.
 
 Each issue or pull request's thread belongs to that GitHub conversation, whoever
-starts its runs. User connections,
-`{messages}` results and automatic GitHub replies are not supported. To act on
+starts its runs. User connections and automatic GitHub replies are not
+supported. To act on
 GitHub from a run (comment, label, open pull requests), give the agent a GitHub
 MCP server in `tools/mcp.ts`.
 
+### Setting up the GitHub App
+
+The first `mda deploy` of a GitHub channel asks which GitHub App it uses, as
+the Slack and Linear channels do:
+
+- **Create a new GitHub App**: deploy asks which account should own it, an
+  organization or your personal account, then opens GitHub with the App filled
+  in and named after the agent. Create it, then install it on the repositories
+  the agent may reach.
+- **Use an existing GitHub App**: enter its App ID, private key file and
+  webhook secret. Deploy records the installation GitHub reports. It asks you
+  to pick one when the App is installed in several accounts, opens the install
+  page when it's installed nowhere, and asks for the installation ID only when
+  GitHub can't be checked.
+
+Agent Auth keeps the App's key, webhook secret and bot ID, so nothing goes into
+`.env`, and later deploys keep the App without asking. An App has one webhook
+URL: if an existing App's webhook points somewhere else, deploy asks before
+moving it to the deployment. Answer "No" to keep it there, for example when
+another service receives the App's events and forwards the ones for this agent
+to `<deployment-url>/channels/github/events` with the body and GitHub's headers
+unchanged. Deploy remembers that URL and doesn't ask again, with or without a
+terminal, until the App's webhook moves. If the App's installation lacks a
+permission the channel needs, deploy names it.
+
+To skip the questions, with or without a terminal, set these in the shell or
+`.env`:
+
+- `MDA_GITHUB_APP_OWNER`: create a new App owned by this organization, or by
+  `@me`, the personal account of whoever creates it.
+- `MDA_GITHUB_APP_ID`, `MDA_GITHUB_APP_PRIVATE_KEY_FILE` (the path to its
+  `.pem` file) and `MDA_GITHUB_WEBHOOK_SECRET`: use this existing App instead.
+  Add `MDA_GITHUB_APP_INSTALLATION_ID` when it's installed in several accounts.
+- `MDA_GITHUB_WEBHOOK_SECRET` alone: the webhook secret of an existing App
+  whose secret Agent Auth doesn't have yet.
+- `MDA_GITHUB_WEBHOOK_ELSEWHERE`: the URL an existing App's webhook keeps.
+  Without a terminal, deploy otherwise stops when the webhook points elsewhere.
+
+Deploy checks them before uploading. Only the CLI reads them: they are never
+uploaded to the deployment, and you can remove them once the channel is set
+up. Without a terminal and without an owner or an existing App, deploy stops
+before uploading and says what to set. During setup it prints the link for a
+person to open and waits up to an hour for them to finish. `GH_WEBHOOK_SECRET`
+and `GH_APP_BOT_ID` (the App bot account's numeric user ID) are different: the
+deployment reads them, and they override what Agent Auth stores.
+
+If a setup step fails once the deployment is live, deploy offers to try again
+or to continue without the GitHub channel. Without a terminal the failure ends
+the deploy, once the other channels are set up. An agent with a GitHub channel
+can't be deployed with `--no-wait`, because setup needs the live deployment.
+
 ## Linear channels
 
 The Linear channel receives a Linear app's webhooks. Each issue is one
@@ -644,37 +1023,76 @@ Slack channel's, such as `assets/icon.png` (at least 256×256 pixels, at most
 the app's icon there. They apply only when deploy creates the app: Linear has
 no API to change an app, so later changes to them do nothing. Change an
 existing app on its settings page in Linear; deploy reminds you of this when
-it keeps an existing app.
-
-`mda deploy` sets up the Linear app, which takes a Linear workspace admin.
-Linear has no public API to create apps, so deploy opens Linear's new-app page
-filled in with the app's name, redirect URI, webhook URL
-(`<deployment-url>/channels/linear/events`) and events. The admin creates the
-app and pastes its client ID, client secret and webhook signing secret into
-deploy's prompts. Deploy asks for the workspace's URL key (as in
-`https://linear.app/<key>/`) first, so the page opens in that workspace. Deploy
-then opens the install page, where the admin approves the app for the
-workspace. Agent Auth keeps the credentials, and the agent's token, so nothing
-goes into `.env`. Without a terminal, for example when a coding agent deploys,
-set `MDA_LINEAR_CLIENT_ID`, `MDA_LINEAR_CLIENT_SECRET` and
-`MDA_LINEAR_WEBHOOK_SECRET` instead, and `MDA_LINEAR_WORKSPACE` to the
-workspace's URL key so the links deploy prints open in that workspace; deploy
-prints the install link. These four are read by the CLI only and never
-uploaded to the deployment. If Linear later stops renewing the app's access,
-the next deploy keeps the app and only asks an admin to approve it again.
-Linear has no API to change an app's webhook URL either, so if the deployment
-moves, update it on the app's page. `mda delete` removes the credentials;
-delete the app itself in Linear.
+it installs the app.
+
+`mda deploy` sets up the Linear app, which takes a Linear workspace admin; see
+[Setting up the Linear app](#setting-up-the-linear-app).
 
 The channel reads the webhook signing secret from Agent Auth, or from
-`LINEAR_WEBHOOK_SECRET` when set. It acts as the app through the agent OAuth
-connection `mda/linear-app/<deployment-id>`, installed with `actor=app`; read
-its token with `await connections.get("mda/linear-token", { type: "agent" })` to call Linear's API from tools.
+`LINEAR_WEBHOOK_SECRET` when set. It acts as the app through the deployment's
+Agent Auth app, whose OAuth connection is `mda/linear-app/<deployment-id>`,
+installed with `actor=app`; read its token with
+`await connections.get("mda/linear-token", { type: "agent" })` to call Linear's API from tools.
+
+`reply: "none"` leaves the run's answer to the agent: the channel doesn't post
+it as a comment or in the session. Session acknowledgements, Stop and error
+notices still post.
 
 [`examples/linear`](../../examples/linear) triages issues in agent sessions,
 shows its steps and plan there, and waits for approval in LangSmith Studio
 before moving an issue to another state.
 
+### Setting up the Linear app
+
+The first `mda deploy` of a Linear channel asks which Linear app it uses, as
+the Slack and GitHub channels do. Setting it up takes a Linear workspace admin:
+
+- **Create a new Linear app**: Linear has no public API to create apps, so
+  deploy asks for the workspace's URL key (as in `https://linear.app/<key>/`)
+  and opens Linear's new-app page in that workspace, filled in with the app's
+  name, redirect URI, webhook URL (`<deployment-url>/channels/linear/events`)
+  and events. The admin creates the app and pastes its client ID, client
+  secret and webhook signing secret into deploy's prompts.
+- **Use an existing Linear app**: deploy lists the redirect URI, webhook URL
+  and events to set on the app's settings page, then asks for the same three
+  values. Linear sends an app's webhooks to one URL, so whatever received them
+  before stops receiving them.
+
+Deploy then opens the install page, where the admin approves the app for the
+workspace. Agent Auth keeps the credentials and the agent's token, so nothing
+goes into `.env`, and later deploys keep the app without asking. If Linear
+stops renewing the app's access, the next deploy keeps the app and only asks
+an admin to approve it again. Linear has no API to change an app, so when the
+channel's `app` settings change or the deployment moves to another URL, update
+the app on its settings page.
+
+To skip the questions, with or without a terminal, set
+`MDA_LINEAR_CLIENT_ID`, `MDA_LINEAR_CLIENT_SECRET` and
+`MDA_LINEAR_WEBHOOK_SECRET` in the shell or `.env`, and `MDA_LINEAR_WORKSPACE`
+to the workspace's URL key so the links deploy prints open in that workspace.
+`MDA_LINEAR_WEBHOOK_SECRET` alone supplies the signing secret of an installed
+app whose secret Agent Auth doesn't have yet. Deploy checks them before
+uploading, and asks Linear whether the client ID and secret belong together.
+Only the CLI reads them: they are never uploaded to the deployment, and you can
+remove them once the channel is set up. Without a terminal and without them,
+deploy stops before uploading with the link to create the app.
+
+An app from these variables wasn't made from deploy's filled-in page, and
+Linear has no API that says what it has set. So before the install link,
+deploy lists the redirect URI, webhook URL and events the app needs, the same
+as for an existing app. In a terminal it waits until you say they're set;
+without one it prints them before the install link for an admin to open.
+Without the redirect URI, Linear answers the install with "Invalid
+redirect_uri".
+
+If a setup step fails once the deployment is live, deploy offers to try again
+or to continue without the Linear channel. Without a terminal the failure ends
+the deploy, once the other channels are set up. An agent with a Linear channel
+can't be deployed with `--no-wait`, because setup needs the live deployment.
+`mda delete` removes the credentials; delete the app itself in Linear.
+Deployments set up by an earlier `mda` keep the app as workspace connections,
+which only a LangSmith workspace admin can delete.
+
 ## HTTP channels
 
 Use `channels.http({ provider, verify, parse, post })` for a provider webhook.
@@ -687,21 +1105,22 @@ A message returned by `parse` contains `userId`, `threadId`, `content`, and `tar
 `threadId` is the stable LangGraph thread UUID. `target` is separate JSON that the
 adapter needs to reply, such as a Photon conversation ID or a Slack channel and
 thread timestamp. MDA keeps this target private and binds it to
-`runtime.channel.post`. The adapter's `post` callback receives the target for
+`runtime.thread.origin.channel.post`. The adapter's `post` callback receives the target for
 reply routing.
 
 `verify` runs first with the original bytes and headers. `verify` and `parse`
 each get a separately readable request body. `parse` owns body decoding and can
 read JSON, form data, text, or bytes. It returns the existing `message` or `ignore`
-result. MDA creates `runtime.channel.event` from the parsed message.
+result. MDA creates `runtime.thread.origin.channel.event` from the parsed message.
 
 To expose provider data, return
 `{ type: "message", message, rawEvent: event }` from `parse`. MDA validates this
-value as finite, acyclic JSON and copies it into `runtime.channel.rawEvent`.
+value as finite, acyclic JSON and copies it into
+`runtime.thread.origin.channel.rawEvent`, in the run that message starts.
 If you omit `rawEvent`, it stays absent. MDA does not decode the body again.
 An explicit `null` is a valid event value.
 
-HTTP and Slack Trigger runs expose delivery through `runtime.channel`.
+HTTP and Slack Trigger runs expose delivery through `runtime.thread.origin.channel`.
 
 The optional method has this signature:
 
@@ -726,9 +1145,11 @@ credentials when it calls the provider API. Native routing or authentication
 fields must not replace them.
 
 Automatic agent replies use the `content` form. An explicit
-`runtime.channel.post({ type: "native", native: ... })` reaches your adapter
+`runtime.thread.origin.channel.post({ type: "native", native: ... })` reaches your adapter
 without conversion. Automatic replies run after the request is accepted. A failed
-`post` is recorded as a delivery error.
+`post` is recorded as a delivery error. `reply: "none"` turns automatic
+replies off, so the agent replies itself; `post` still serves
+`runtime.channel.post` and error notices.
 If `post` is omitted, the channel can receive events and exposes facts, but
 has no runtime `post` method. The webhook path is `/channels/<name>/events`, where
 `<name>` is the channel file name. An existing Photon webhook needs no URL change
@@ -805,7 +1226,9 @@ a handler's result. `null` or HTTP 204 starts nothing. A GitHub event also
 carries what a handler gets beside the payload: its `action`, `repository`,
 `sender` and `mentions`, so a service checks them as a handler does. These are
 optional in `GitHubEndpointRequest`, so a receiver takes requests from older
-deployments.
+deployments. A Slack message carries its `text`, `userId`, `channelId`,
+`messageTs`, `threadTs` and `files` the same way, with Slack's own event as
+`payload`.
 
 ```ts
 const backend = new Request(`${process.env.BACKEND_URL}/linear/runs`, {
@@ -822,8 +1245,8 @@ export const channel = channels.linear({
 });
 ```
 
-GitHub or Linear gets its answer first, and MDA asks the service in the
-background, so a slow service doesn't time out the delivery. A network error
+GitHub, Linear or Trigger Server gets its answer first, and MDA asks the
+service in the background, so a slow service doesn't time out the delivery. A network error
 before the answer, HTTP 429 or a 5xx is tried again, up to three attempts with
 the same `webhook-id`. Another error status, a redirect, an answer cut off or
 that isn't one of these, more than 10 MB, or no answer within 60 seconds fails the handler, as a
@@ -855,8 +1278,9 @@ const event = new Webhook(process.env.ENDPOINT_SECRET!).verify(
 );
 ```
 
-On the service's side, `LinearEndpointRequest<K>` and
-`GitHubEndpointRequest<K>` type what the channel sends, `{ event: { key,
+On the service's side, `LinearEndpointRequest<K>`,
+`GitHubEndpointRequest<K>` and `SlackEndpointRequest<K>` type what the channel
+sends, `{ event: { key,
 deliveryId, payload }, thread }`, with the payload typed by the event key, and
 `EndpointAnswer` types an answer, all JSON; answer `null` to start nothing. The
 request types are types only: validate the body as your service validates
@@ -987,8 +1411,34 @@ await runtime.schedules!.create({
 ```
 
 Set `newThread` to choose whether a run starts a new thread or continues the
-current thread. When a schedule is created from a channel such as Slack,
-each run posts its final answer to that channel. Runtime schedules stay when you deploy again.
+current thread. When a schedule is created on a channel's thread, such as a
+Slack thread, each run posts its final answer to that channel. A same-thread
+schedule posts wherever the thread's origin points when it runs, so its record
+has `channel: null` and `target: null`. A new-thread schedule keeps the
+conversation it was created in. On Slack, each run starts a new Slack thread
+there, with its answer or, when it waits on a decision, with a notice. Replies
+and decisions in that Slack thread continue the run's thread. Runtime schedules
+stay when you deploy again.
+
+A user schedule can run as another person on the thread. Pass one of
+`runtime.thread.participants` as `runAs`; the caller still owns the schedule
+and is the one who can list, update, and delete it. Runs act as that person,
+with their connections.
+
+```ts
+const me = runtime.serverInfo?.principal?.id;
+const bob = runtime.thread!.participants.find(({ id }) => id !== me);
+await runtime.schedules!.create({
+  owner: { type: "user" },
+  cron: "0 9 * * 1",
+  prompt: "Remind Bob about the weekly report.",
+  newThread: false,
+  runAs: bob,
+});
+```
+
+`runAs` needs `owner: { type: "user" }` and a participant with the same id and
+role; anything else is an error. The schedule's record shows it as `runAs`.
 
 Each owner can have at most 20 runtime schedules per agent, paused ones
 included. Set `MDA_MAX_AGENT_SCHEDULES` or `MDA_MAX_USER_SCHEDULES` in the
@@ -1068,9 +1518,6 @@ server. In `mda dev`, an agent-owned connection reads from
 slashes to double underscores (`mda/github-token` → `MDA_DEV_MDA__GITHUB_TOKEN`).
 Hosted deployments resolve workspace connections from Agent Auth:
 
-The old `connectors/mcp.ts` file API remains available with a warning during
-`0.7.x`. It will be removed in `0.8.0`.
-
 ```ts
 import { defineMcp, connections } from "managed-deepagents";