@workser/cli 0.6.28 → 0.6.29

package/dist/index.js

@@ -3810,6 +3810,12 @@ sending it. That matters: the API silently drops unknown fields, so a typo
 would otherwise be accepted, dropped, and reported as success \u2014 leaving an
 agent that had been told nothing.
 
+## Nothing starts it until you give it a trigger
+
+A published agent runs when asked and at no other time. A time, a chat message
+or an app event is a **trigger**, and it works the moment it is saved \u2014 it is
+not part of the agent's version. \`workser help agent-triggers\`.
+
 ## Nothing takes effect until you publish
 
 **This is the step to not forget.** The runtime resolves the PUBLISHED version
@@ -3955,15 +3961,85 @@ watching sees the agent think. See the \`workser-sdk\` skill, \`reference/agents
    single biggest cause of an agent that "doesn't work".
 
 3. **Every plan can run agents once the shared wallet has enough credits.** A
-   \`402\` with \`spend_limit_reached\` means the wallet needs a top-up (or the owner
-   reached their own spend cap). Tell them exactly what it says and hand over
-   the credit action; never suggest a subscription upgrade for this refusal.
+   \`402\` with \`insufficient_credits\` needs a top-up; \`spend_limit_reached\` means
+   the owner reached the guard rail they set. Tell them exactly what it says and
+   hand over the matching action; never suggest a subscription upgrade.
 
 4. **Say who it is for.** An agent acting for one of the app's customers needs
    \`referenceUserId\`, or its memory and audit trail belong to nobody.
 
 5. **Do not invent an agent the user did not ask for.** Creating one is cheap;
    an agent nobody wanted, quietly costing money per run, is not.
+`
+  },
+  {
+    topic: "agent-triggers",
+    title: "What starts an Agent Cloud agent",
+    summary: "Schedules, chat channels and app events \u2014 a trigger works the moment it is saved, unlike everything else on an agent.",
+    commands: [],
+    source: "skills/workser/reference/agent-triggers.md",
+    body: `# What starts an Agent Cloud agent
+
+A published agent runs when somebody asks it to and at no other time. A trigger
+is what makes it start on its own \u2014 a time, a chat message, or an event in a
+connected app.
+
+\`\`\`
+workser agent-cloud triggers <id>                       # what starts it today
+workser agent-cloud trigger-add <id> schedule cron="0 9 * * 1-5" name="Morning report"
+workser agent-cloud trigger-add <id> chat app_type=line
+workser agent-cloud trigger-add <id> app_event event_type=GMAIL_NEW_GMAIL_MESSAGE connected_account_id=<id>
+workser agent-cloud trigger-setup <id> <triggerId>      # the webhook URL to paste
+workser agent-cloud trigger-events <id>                 # what fired, and what it started
+workser agent-cloud trigger-remove <id> <triggerId>
+\`\`\`
+
+**A trigger works the moment it is saved** \u2014 unlike everything above, it is not
+part of the agent's version and does not wait for a publish.
+
+\`rule=\` is optional and is the FIRING rule, not the agent's instructions:
+\`rule="only when the message mentions an order"\`. Leave it empty on a chat
+channel and every message reaches the agent, which is what a support agent
+wants \u2014 the agent decides what to do with each one.
+
+For a chat trigger, **\`trigger-setup\` is not optional**: it returns the webhook
+URL to paste into LINE's or Slack's console, and it says whether anything has
+arrived yet. Without that step the trigger sits there looking finished and
+never receives anything.
+
+To let the agent ANSWER on that channel, the project also needs the account
+connected \u2014 \`workser line connect --token \u2026\`. See \`workser help chat-channels\`.
+
+## The two halves of a chat agent
+
+Receiving and answering are separate, and each has its own setup:
+
+| | What it does | How |
+| --- | --- | --- |
+| The trigger | a message STARTS the agent | \`trigger-add <id> chat app_type=line\`, then \`trigger-setup\` |
+| The connection | the agent can ANSWER | \`workser line connect --token \u2026\` |
+
+Do only the first and the agent listens and never speaks. Do only the second and
+nothing ever wakes it up.
+
+With both in place, a run started by a message is handed the reply token and the
+sender, and gets every operation of that account as a tool \u2014 \`line_reply\`,
+\`slack_send_message\` and the rest. Sends go through the agent's approval gate;
+reads do not.
+
+## Schedules, in plain words
+
+\`cron=\` takes a standard five-field expression. The four people ask for:
+
+\`\`\`
+cron="0 9 * * 1-5"    every weekday at 9am
+cron="0 9 * * *"      every day at 9am
+cron="0 * * * *"      every hour
+cron="0 9 * * 1"      every Monday at 9am
+\`\`\`
+
+\`timezone=\` defaults to UTC, which is almost never what somebody means by "9am".
+Set it: \`timezone="Asia/Bangkok"\`.
 `
   },
   {
@@ -4381,6 +4457,113 @@ copy is the current one.
 \`workser business\` is how **you** inspect and fix data while building. The app reads
 the same records at runtime through \`workser.business\` in \`@workser/app\` \u2014 see the
 \`workser-sdk\` skill. An app shelling out to this CLI per request is wrong.
+`
+  },
+  {
+    topic: "chat-channels",
+    title: "LINE, Telegram, Discord, Slack",
+    summary: "Connect a chat account once, then send, reply and read from the CLI or from an agent \u2014 LINE gets its whole Messaging API.",
+    commands: ["line", "telegram", "discord", "slack"],
+    source: "skills/workser/reference/chat-channels.md",
+    body: `# LINE, Telegram, Discord, Slack
+
+Connect the business's chat account to this project **once**. After that it is
+reachable from here, from Workser Code, and from any Agent Cloud agent in this
+project \u2014 including the one a chat message starts.
+
+Every provider takes the same six verbs:
+
+\`\`\`
+workser <provider> status                       # is anything connected?
+workser <provider> connect --token <token>
+workser <provider> verify                       # does the credential still work?
+workser <provider> disconnect
+workser <provider> ops [--group <name>]         # everything it can do
+workser <provider> call <operation> --params '<json>'
+\`\`\`
+
+where \`<provider>\` is \`line\`, \`telegram\`, \`discord\` or \`slack\`.
+
+## Getting the token
+
+| Provider | Where | Flag |
+| --- | --- | --- |
+| LINE | Developers console \u2192 Messaging API \u2192 Channel access token | \`--token\`, plus \`--secret\` for the channel secret |
+| Telegram | @BotFather \u2192 \`/newbot\` or \`/token\` | \`--token\` |
+| Discord | Developer Portal \u2192 your app \u2192 Bot \u2192 Reset Token | \`--token\` (the bot must also be invited to the server) |
+| Slack | Your app \u2192 OAuth & Permissions \u2192 Bot User OAuth Token (\`xoxb-\`) | \`--token\`, plus \`--signing-secret\` |
+
+\`connect\` calls the provider immediately to prove the credential works, so a
+mistyped token fails right there instead of an hour later as a customer message
+nobody answered.
+
+## \`call\` is the whole API
+
+\`ops\` prints every operation with a one-line summary. The \`\u25CF\` marks the ones
+that send something, spend quota, or change the account.
+
+\`\`\`
+workser line call push --params '{"to":"U4af\u2026","messages":[{"type":"text","text":"Your order shipped"}]}'
+workser line call richmenu_list
+workser telegram call send_chat_action --params '{"chat_id":123,"action":"typing"}'
+workser slack call list_conversations --params '{"types":"public_channel"}'
+workser discord call create_thread --params '{"channel_id":"\u2026","message_id":"\u2026","name":"Order #4021"}'
+\`\`\`
+
+Parameters are flat \u2014 path, query and body fields all go in \`--params\` together
+and the server sorts them. Fields it has never heard of are **forwarded
+untouched**, so a flex component or a Slack block the vendor shipped last week
+works today.
+
+## Shortcuts
+
+\`\`\`
+workser line send <to> "<text>" | reply <replyToken> "<text>" | broadcast "<text>"
+workser line quota | profile <userId>
+workser telegram send <chatId> "<text>"
+workser discord send <channelId> "<text>"
+workser slack send <channel> "<text>"
+\`\`\`
+
+## Reply beats push, on LINE
+
+\`reply\` uses the token that came with the incoming message. It is **free** and
+does not touch the monthly quota; \`push\` costs one message per recipient. The
+token is single-use and expires within a minute or so, so reply first and fall
+back to push.
+
+\`broadcast\` sends to every follower and spends one message each. On a large
+account that is the most expensive call available \u2014 say what it will cost
+before running it.
+
+## How complete each one is
+
+**LINE is the deep one** \u2014 its entire Messaging API, about seventy operations:
+messaging, rich menus, audiences and narrowcast, insight, quota, content,
+groups and rooms, and the webhook endpoint itself.
+
+**Telegram, Discord and Slack carry what a chat agent needs** \u2014 send, reply,
+edit, delete, react, typing indicator, threads and DMs, plus reading people and
+conversations. Not their whole APIs. \`ops\` is the truth; ask it rather than
+assuming an operation exists.
+
+## Rich menus, in order (LINE)
+
+A rich menu does nothing until it has both a picture and a place to appear:
+
+1. \`richmenu_create\` \u2014 the layout and tappable areas. Returns an id.
+2. \`richmenu_upload_image\` \u2014 \`content\` is the file **base64-encoded**, with
+   \`content_type\`. The image must match the declared size exactly.
+3. \`richmenu_set_default\` (everybody) or \`richmenu_link_user\` (one person).
+
+\`richmenu_validate\` checks a layout without creating it.
+
+## When it is an agent doing this
+
+An Agent Cloud agent in a project with a connected account gets these as tools
+automatically \u2014 there is nothing to bind, and no capability to switch on. Sends
+go through the agent's approval gate; reads do not. See
+\`workser help agent-cloud\`.
 `
   },
   {
@@ -5177,87 +5360,6 @@ deployment keeps using whatever it was built with until it's redeployed \u2014
 run \`workser deploy\` (\`--prod\` for the production key) to pick up the new
 value. \`key rotate\` prints the new secret exactly once; it is never shown
 again or stored anywhere in the clear.
-`
-  },
-  {
-    topic: "line",
-    title: "LINE Official Account",
-    summary: "Connect a LINE OA once, then send, reply, broadcast, build rich menus and read insight \u2014 from the CLI or from an agent.",
-    commands: ["line"],
-    source: "skills/workser/reference/line.md",
-    body: `# LINE Official Account
-
-Connect the business's LINE account to this project **once**. After that the same
-account is reachable from here, from Workser Code, and from any Agent Cloud agent
-in this project \u2014 including the one a LINE message starts.
-
-\`\`\`
-workser line status                          # is anything connected?
-workser line connect --token <channelAccessToken> [--secret <channelSecret>]
-workser line verify                          # ask LINE if the token still works
-workser line disconnect
-
-workser line ops [--group messaging|richmenu|audience|insight|people|group|quota|content|account]
-workser line call <operation> --params '<json>'   # any of the 70 operations
-
-workser line send <to> "<text>"              # push to a user, group or room id
-workser line reply <replyToken> "<text>"     # answer a message \u2014 free, single-use
-workser line broadcast "<text>"              # EVERY follower, one message each
-workser line quota                           # allowance left this month
-workser line profile <userId>
-\`\`\`
-
-## Getting the token
-
-LINE Developers console \u2192 your Messaging API channel \u2192 **Messaging API** tab \u2192
-*Channel access token* (long-lived). \`--secret\` is the **Basic settings** \u2192
-*Channel secret*, and is only needed if you want LINE's own signature check on
-incoming webhooks.
-
-\`connect\` calls LINE immediately to prove the token works, so a mistyped token
-fails here rather than an hour later as a customer message nobody answered.
-
-## \`call\` is the whole API
-
-\`ops\` prints every operation with a one-line summary. The \`\u25CF\` marks the ones that
-send something, spend quota, or change the account.
-
-\`\`\`
-workser line call push --params '{"to":"U4af\u2026","messages":[{"type":"text","text":"Your order shipped"}]}'
-workser line call richmenu_list
-workser line call insight_followers --params '{"date":"20260909"}'
-workser line call webhook_endpoint_set --params '{"endpoint":"https://\u2026"}'
-\`\`\`
-
-Parameters are flat \u2014 path, query and body fields all go in \`--params\` together and
-the server sorts them. Fields it has never heard of are **forwarded to LINE
-untouched**, so a flex component LINE shipped last week works today.
-
-## Reply beats push
-
-\`reply\` uses the token that came with the incoming message. It is **free** and does
-not touch the monthly quota; \`push\` costs one message per recipient. The token is
-single-use and expires within a minute or so, so reply first and fall back to push.
-
-\`broadcast\` sends to every follower and spends one message each. On a large account
-that is the most expensive call in the list \u2014 say what it will cost before running it.
-
-## Rich menus, in order
-
-A rich menu does nothing until it has both a picture and a place to appear:
-
-1. \`richmenu_create\` \u2014 the layout and tappable areas. Returns an id.
-2. \`richmenu_upload_image\` \u2014 \`content\` is the file **base64-encoded**, with
-   \`content_type\`. The image must match the declared size exactly.
-3. \`richmenu_set_default\` (everybody) or \`richmenu_link_user\` (one person).
-
-\`richmenu_validate\` checks a layout without creating it.
-
-## When it is an agent doing this
-
-An Agent Cloud agent in a project with a connected LINE account gets these as tools
-automatically \u2014 there is nothing to bind. Sends go through the agent's approval gate;
-reads do not. See \`workser help agent-cloud\`.
 `
   },
   {
@@ -8372,6 +8474,118 @@ function registerAgentCloud(program3) {
       });
     })
   );
+  cloud.command("triggers <agentId>").description("What starts this agent \u2014 schedules, chat channels, app events").action(
+    action(async ({ ctx, args }) => {
+      const res = await api(
+        ctx,
+        `/v1/agent-cloud/${encodeURIComponent(args[0])}/triggers`
+      );
+      const items = res?.triggers ?? [];
+      ok(res, () => {
+        if (!items.length) {
+          return line(
+            import_picocolors17.default.dim("Nothing starts this agent yet \u2014 it only runs when asked.")
+          );
+        }
+        for (const t of items) {
+          const state = t.status === "active" ? import_picocolors17.default.green("on") : import_picocolors17.default.yellow(t.status);
+          const when = t.schedule_config?.cron_expression ?? t.app_event_config?.event_source ?? t.app_event_config?.event_type ?? "";
+          line(
+            `${import_picocolors17.default.bold(t.name ?? t.trigger_type)}  ${state}  ${import_picocolors17.default.dim(when)}`
+          );
+          line("  " + import_picocolors17.default.dim(t.id));
+        }
+      });
+    })
+  );
+  cloud.command("trigger-add <agentId> <kind> [pairs...]").description(
+    "Start an agent on a schedule, a chat channel or an app event. kind is schedule | chat | app_event. e.g. trigger-add <id> chat app_type=line"
+  ).action(
+    action(async ({ ctx, args }) => {
+      const kind = String(args[1]);
+      const pairs = parsePairs(
+        args[2] ?? [],
+        [
+          "name",
+          "rule",
+          "cron",
+          "timezone",
+          "app_type",
+          "event_type",
+          "connected_account_id"
+        ]
+      );
+      const body = buildTriggerBody(kind, pairs);
+      const res = await api(
+        ctx,
+        `/v1/agent-cloud/${encodeURIComponent(args[0])}/triggers`,
+        { method: "POST", body }
+      );
+      ok(res, () => {
+        line(import_picocolors17.default.green("Added.") + "  " + import_picocolors17.default.dim(res?.trigger?.id ?? ""));
+        if (kind === "chat") {
+          line(
+            import_picocolors17.default.dim("Now get the webhook URL to paste into the platform: ") + import_picocolors17.default.bold(
+              `workser agent-cloud trigger-setup ${args[0]} ${res?.trigger?.id ?? "<triggerId>"}`
+            )
+          );
+        }
+      });
+    })
+  );
+  cloud.command("trigger-setup <agentId> <triggerId>").description("The webhook URL and console steps for a chat trigger").action(
+    action(async ({ ctx, args }) => {
+      const res = await api(
+        ctx,
+        `/v1/agent-cloud/${encodeURIComponent(args[0])}/triggers/${encodeURIComponent(args[1])}/setup`
+      );
+      ok(res, () => {
+        line(import_picocolors17.default.bold(`Connect ${res?.label ?? "this channel"}`));
+        line("");
+        line(import_picocolors17.default.bold("Webhook URL"));
+        line("  " + (res?.webhook_url ?? import_picocolors17.default.dim("\u2014")));
+        if (res?.verify_token) {
+          line(import_picocolors17.default.bold("Verify token"));
+          line("  " + res.verify_token);
+        }
+        line("");
+        for (const step of res?.setup_steps ?? []) line("  " + import_picocolors17.default.dim(step));
+        line("");
+        line(
+          res?.is_verified ? import_picocolors17.default.green(`Receiving \u2014 ${res.event_count ?? 0} events so far.`) : import_picocolors17.default.yellow("Nothing has arrived yet.")
+        );
+      });
+    })
+  );
+  cloud.command("trigger-remove <agentId> <triggerId>").description("Stop something from starting this agent").action(
+    action(async ({ ctx, args }) => {
+      const res = await api(
+        ctx,
+        `/v1/agent-cloud/${encodeURIComponent(args[0])}/triggers/${encodeURIComponent(args[1])}`,
+        { method: "DELETE" }
+      );
+      ok(res, () => line("Removed."));
+    })
+  );
+  cloud.command("trigger-events <agentId>").description("What has fired lately, and whether it started the agent").option("--limit <n>", "how many to show").action(
+    action(async ({ ctx, args, opts }) => {
+      const res = await api(
+        ctx,
+        `/v1/agent-cloud/${encodeURIComponent(args[0])}/trigger-events`,
+        { query: { limit: opts.limit } }
+      );
+      const items = res?.events ?? [];
+      ok(res, () => {
+        if (!items.length) return line(import_picocolors17.default.dim("Nothing has fired yet."));
+        for (const e of items) {
+          const state = e.status === "matched" ? import_picocolors17.default.green("started the agent") : e.status === "failed" ? import_picocolors17.default.red("failed") : import_picocolors17.default.yellow(e.status);
+          line(`${state}  ${e.summary ?? e.trigger_name ?? ""}`);
+          if (e.error_message) line("  " + import_picocolors17.default.red(e.error_message));
+          else if (e.reasoning) line("  " + import_picocolors17.default.dim(e.reasoning));
+        }
+      });
+    })
+  );
   cloud.command("publish <agentId>").description("Put the current setup live \u2014 nothing takes effect until this runs").option("--note <text>", "What changed, for the version history").action(
     action(async ({ ctx, args, opts }) => {
       const res = await api(ctx, `/v1/agent-cloud/${encodeURIComponent(args[0])}/publish`, {
@@ -8554,6 +8768,60 @@ function parsePairs(pairs, allowed) {
   }
   return out;
 }
+function buildTriggerBody(kind, pairs) {
+  const base = {
+    name: pairs.name,
+    rule: pairs.rule
+  };
+  if (kind === "schedule") {
+    if (!pairs.cron) {
+      throw new Error(
+        'A schedule needs cron=, e.g. cron="0 9 * * 1-5" for every weekday at 9am.'
+      );
+    }
+    return {
+      ...base,
+      trigger_type: "schedule",
+      name: pairs.name ?? "Scheduled run",
+      schedule_config: {
+        cron_expression: pairs.cron,
+        timezone: pairs.timezone ?? "UTC"
+      }
+    };
+  }
+  if (kind === "chat") {
+    if (!pairs.app_type) {
+      throw new Error(
+        "A chat trigger needs app_type=, one of: line, telegram, discord, slack, facebook_messenger, instagram, whatsapp, twitter, custom."
+      );
+    }
+    return {
+      ...base,
+      trigger_type: "chat_webhook",
+      chat_webhook_config: {
+        app_type: pairs.app_type,
+        event_type: pairs.event_type ?? "message"
+      }
+    };
+  }
+  if (kind === "app_event") {
+    if (!pairs.event_type || !pairs.connected_account_id) {
+      throw new Error(
+        "An app-event trigger needs event_type= and connected_account_id= (see `workser connection list`)."
+      );
+    }
+    return {
+      ...base,
+      trigger_type: "app_event",
+      name: pairs.name ?? pairs.event_type,
+      app_event_config: {
+        event_type: pairs.event_type,
+        connected_account_id: pairs.connected_account_id
+      }
+    };
+  }
+  throw new Error(`Unknown kind "${kind}". One of: schedule | chat | app_event`);
+}
 
 // src/commands/verify.ts
 var import_picocolors18 = __toESM(require_picocolors(), 1);
@@ -8879,59 +9147,142 @@ function registerConnection(program3) {
   );
 }
 
-// src/commands/line.ts
+// src/commands/channel.ts
 var import_picocolors23 = __toESM(require_picocolors(), 1);
-function registerLine(program3) {
-  const cmd = program3.command("line").description("Connect a LINE Official Account and use the LINE Messaging API");
-  cmd.command("status").description("Show this project's LINE connection").action(
+var SHAPES = [
+  {
+    id: "line",
+    label: "LINE",
+    description: "Connect a LINE Official Account and use the LINE Messaging API",
+    tokenField: "channel_access_token",
+    tokenHelp: "Messaging API tab \u2192 Channel access token",
+    extra: {
+      flag: "--secret <channelSecret>",
+      field: "channel_secret",
+      help: "Basic settings \u2192 Channel secret (for webhook signatures)"
+    },
+    send: {
+      operation: "push",
+      build: (to, text) => ({ to, messages: [{ type: "text", text }] })
+    },
+    reply: {
+      operation: "reply",
+      build: (replyToken, text) => ({
+        replyToken,
+        messages: [{ type: "text", text }]
+      })
+    }
+  },
+  {
+    id: "telegram",
+    label: "Telegram",
+    description: "Connect a Telegram bot and message chats, groups and channels",
+    tokenField: "bot_token",
+    tokenHelp: "The token @BotFather gave you",
+    send: {
+      operation: "send_message",
+      build: (chat_id, text) => ({ chat_id, text })
+    }
+  },
+  {
+    id: "discord",
+    label: "Discord",
+    description: "Connect a Discord bot and post in servers and DMs",
+    tokenField: "bot_token",
+    tokenHelp: "Developer Portal \u2192 your application \u2192 Bot \u2192 Reset Token",
+    send: {
+      operation: "send_message",
+      build: (channel_id, content) => ({ channel_id, content })
+    }
+  },
+  {
+    id: "slack",
+    label: "Slack",
+    description: "Connect a Slack app and post in channels and DMs",
+    tokenField: "bot_token",
+    tokenHelp: "OAuth & Permissions \u2192 Bot User OAuth Token (starts xoxb-)",
+    extra: {
+      flag: "--signing-secret <secret>",
+      field: "signing_secret",
+      help: "Basic Information \u2192 Signing Secret (for event signatures)"
+    },
+    send: {
+      operation: "send_message",
+      build: (channel, text) => ({ channel, text })
+    }
+  }
+];
+function registerChannels(program3) {
+  for (const shape of SHAPES) register(program3, shape);
+}
+function register(program3, shape) {
+  const cmd = program3.command(shape.id).description(shape.description);
+  const path = (suffix = "") => (projectId) => `/v1/projects/${projectId}/channels/${shape.id}${suffix}`;
+  cmd.command("status").description(`Show this project's ${shape.label} connection`).action(
     action(async ({ ctx }) => {
       const projectId = requireProject(ctx);
-      const res = await api(ctx, `/v1/projects/${projectId}/line`);
+      const res = await api(ctx, path()(projectId));
       ok(res, () => {
         const c = res?.connection;
-        if (!c) return line(import_picocolors23.default.dim("No LINE account connected. Run `workser line connect`."));
+        if (!c) {
+          return line(
+            import_picocolors23.default.dim(
+              `No ${shape.label} account connected. Run \`workser ${shape.id} connect\`.`
+            )
+          );
+        }
         const state = c.status === "connected" ? import_picocolors23.default.green(c.status) : import_picocolors23.default.yellow(c.status);
-        line(`${import_picocolors23.default.bold(c.display_name ?? "LINE")}  ${state}`);
-        if (c.public_config?.basic_id) line(import_picocolors23.default.dim(`  ${c.public_config.basic_id}`));
+        line(`${import_picocolors23.default.bold(c.display_name ?? shape.label)}  ${state}`);
+        for (const [k, v] of Object.entries(c.public_config ?? {})) {
+          if (v) line(import_picocolors23.default.dim(`  ${k}: ${v}`));
+        }
         if (c.last_error) line(import_picocolors23.default.red(`  ${c.last_error}`));
       });
     })
   );
-  cmd.command("connect").description("Connect a LINE Official Account with its channel access token").requiredOption("--token <channelAccessToken>", "Messaging API \u2192 Channel access token").option("--secret <channelSecret>", "Basic settings \u2192 Channel secret (for webhook signatures)").action(
+  const connect = cmd.command("connect").description(`Connect a ${shape.label} account to this project`).requiredOption("--token <token>", shape.tokenHelp);
+  if (shape.extra) connect.option(shape.extra.flag, shape.extra.help);
+  connect.action(
     action(async ({ ctx, opts }) => {
       const projectId = requireProject(ctx);
-      const res = await api(ctx, `/v1/projects/${projectId}/line/connect`, {
-        body: { channel_access_token: opts.token, channel_secret: opts.secret }
-      });
+      const body = {};
+      body[shape.tokenField] = String(opts.token);
+      if (shape.extra) {
+        const key = shape.extra.flag.split(" ")[0].replace(/^--/, "").replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+        if (opts[key]) body[shape.extra.field] = opts[key];
+      }
+      const res = await api(ctx, path("/connect")(projectId), { body });
       ok(
         res,
-        () => line(`Connected ${import_picocolors23.default.bold(res?.connection?.display_name ?? "LINE")}.`)
+        () => line(
+          `Connected ${import_picocolors23.default.bold(res?.connection?.display_name ?? shape.label)}.`
+        )
       );
     })
   );
-  cmd.command("verify").description("Ask LINE whether the stored token still works").action(
+  cmd.command("verify").description(`Ask ${shape.label} whether the stored credential still works`).action(
     action(async ({ ctx }) => {
       const projectId = requireProject(ctx);
-      const res = await api(ctx, `/v1/projects/${projectId}/line/verify`, { body: {} });
+      const res = await api(ctx, path("/verify")(projectId), { body: {} });
       ok(res, () => {
         const c = res?.connection;
         line(
-          c?.status === "connected" ? import_picocolors23.default.green("The token still works.") : import_picocolors23.default.red(c?.last_error ?? "LINE refused the stored token.")
+          c?.status === "connected" ? import_picocolors23.default.green("The credential still works.") : import_picocolors23.default.red(c?.last_error ?? `${shape.label} refused it.`)
         );
       });
     })
   );
-  cmd.command("disconnect").description("Disconnect LINE from this project").action(
+  cmd.command("disconnect").description(`Disconnect ${shape.label} from this project`).action(
     action(async ({ ctx }) => {
       const projectId = requireProject(ctx);
-      const res = await api(ctx, `/v1/projects/${projectId}/line`, { method: "DELETE" });
+      const res = await api(ctx, path()(projectId), { method: "DELETE" });
       ok(res, () => line("Disconnected."));
     })
   );
-  cmd.command("ops").description("List every LINE operation, optionally filtered by group").option("--group <name>", "messaging, richmenu, audience, insight, people, group, quota, content, account, validation").action(
+  cmd.command("ops").description(`List every ${shape.label} operation`).option("--group <name>", "filter to one group").action(
     action(async ({ ctx, opts }) => {
       const projectId = requireProject(ctx);
-      const res = await api(ctx, `/v1/projects/${projectId}/line/operations`);
+      const res = await api(ctx, path("/operations")(projectId));
       const all = res?.operations ?? [];
       const items = opts.group ? all.filter((o) => o.group === opts.group) : all;
       ok(items, () => {
@@ -8946,87 +9297,116 @@ ${group}`));
           const mark = o.writes ? import_picocolors23.default.yellow(" \u25CF") : "  ";
           line(`${mark} ${import_picocolors23.default.bold(o.id.padEnd(28))} ${o.summary}`);
         }
-        line(import_picocolors23.default.dim("\n\u25CF sends something, spends quota, or changes the account."));
+        line(
+          import_picocolors23.default.dim(
+            "\n\u25CF sends something, spends quota, or changes the account."
+          )
+        );
+        for (const note of res?.excludes ?? []) {
+          line(import_picocolors23.default.dim(`  not included \u2014 ${note}`));
+        }
       });
     })
   );
-  cmd.command("call <operation>").description("Run any LINE operation \u2014 see `workser line ops`").option("--params <json>", "the operation's parameters as a JSON string", "{}").action(
+  cmd.command("call <operation>").description(`Run any ${shape.label} operation \u2014 see \`workser ${shape.id} ops\``).option("--params <json>", "the operation's parameters as a JSON string", "{}").action(
     action(async ({ ctx, args, opts }) => {
       const projectId = requireProject(ctx);
-      const res = await callLine(ctx, projectId, args[0], parseParams(opts.params));
-      ok(res, () => line(JSON.stringify(res?.data ?? res, null, 2)));
-    })
-  );
-  cmd.command("send <to> <text>").description("Send a text message to a user, group or room id").action(
-    action(async ({ ctx, args }) => {
-      const projectId = requireProject(ctx);
-      const res = await callLine(ctx, projectId, "push", {
-        to: args[0],
-        messages: [{ type: "text", text: args[1] }]
-      });
-      ok(res, () => report(res, "Sent."));
-    })
-  );
-  cmd.command("reply <replyToken> <text>").description("Answer a message using its reply token (free, and single-use)").action(
-    action(async ({ ctx, args }) => {
-      const projectId = requireProject(ctx);
-      const res = await callLine(ctx, projectId, "reply", {
-        replyToken: args[0],
-        messages: [{ type: "text", text: args[1] }]
-      });
-      ok(res, () => report(res, "Replied."));
-    })
-  );
-  cmd.command("broadcast <text>").description("Send a text message to EVERY follower \u2014 spends one message each").action(
-    action(async ({ ctx, args }) => {
-      const projectId = requireProject(ctx);
-      const res = await callLine(ctx, projectId, "broadcast", {
-        messages: [{ type: "text", text: args[0] }]
-      });
-      ok(res, () => report(res, "Broadcast sent."));
-    })
-  );
-  cmd.command("quota").description("How much of this month's message allowance is left").action(
-    action(async ({ ctx }) => {
-      const projectId = requireProject(ctx);
-      const [quota, used] = await Promise.all([
-        callLine(ctx, projectId, "quota", {}),
-        callLine(ctx, projectId, "quota_consumption", {})
-      ]);
-      ok({ quota: quota?.data, consumption: used?.data }, () => {
-        const limit = quota?.data?.value;
-        const spent = used?.data?.totalUsage;
-        if (limit === void 0) return line(JSON.stringify(quota?.data ?? quota, null, 2));
-        line(`${spent ?? "?"} of ${limit} messages used this month.`);
-      });
-    })
-  );
-  cmd.command("profile <userId>").description("Look up one follower").action(
-    action(async ({ ctx, args }) => {
-      const projectId = requireProject(ctx);
-      const res = await callLine(ctx, projectId, "profile", { userId: args[0] });
+      const res = await call(ctx, projectId, shape, args[0], parseParams(opts.params));
       ok(res, () => line(JSON.stringify(res?.data ?? res, null, 2)));
     })
   );
+  if (shape.send) {
+    const send = shape.send;
+    cmd.command("send <to> <text>").description(
+      shape.id === "discord" ? "Post a text message in a Discord channel id" : shape.id === "slack" ? "Post a text message in a Slack channel or DM id" : "Send a text message to a chat, user, group or room id"
+    ).action(
+      action(async ({ ctx, args }) => {
+        const projectId = requireProject(ctx);
+        const res = await call(
+          ctx,
+          projectId,
+          shape,
+          send.operation,
+          send.build(args[0], args[1])
+        );
+        ok(res, () => report(res, "Sent."));
+      })
+    );
+  }
+  if (shape.reply) {
+    const reply = shape.reply;
+    cmd.command("reply <token> <text>").description("Answer a message using its reply token \u2014 free, and single-use").action(
+      action(async ({ ctx, args }) => {
+        const projectId = requireProject(ctx);
+        const res = await call(
+          ctx,
+          projectId,
+          shape,
+          reply.operation,
+          reply.build(args[0], args[1])
+        );
+        ok(res, () => report(res, "Replied."));
+      })
+    );
+  }
+  if (shape.id === "line") {
+    cmd.command("broadcast <text>").description("Send a text message to EVERY follower \u2014 spends one message each").action(
+      action(async ({ ctx, args }) => {
+        const projectId = requireProject(ctx);
+        const res = await call(ctx, projectId, shape, "broadcast", {
+          messages: [{ type: "text", text: args[0] }]
+        });
+        ok(res, () => report(res, "Broadcast sent."));
+      })
+    );
+    cmd.command("quota").description("How much of this month's message allowance is left").action(
+      action(async ({ ctx }) => {
+        const projectId = requireProject(ctx);
+        const [quota, used] = await Promise.all([
+          call(ctx, projectId, shape, "quota", {}),
+          call(ctx, projectId, shape, "quota_consumption", {})
+        ]);
+        ok({ quota: quota?.data, consumption: used?.data }, () => {
+          const limit = quota?.data?.value;
+          const spent = used?.data?.totalUsage;
+          if (limit === void 0) {
+            return line(JSON.stringify(quota?.data ?? quota, null, 2));
+          }
+          line(`${spent ?? "?"} of ${limit} messages used this month.`);
+        });
+      })
+    );
+    cmd.command("profile <userId>").description("Look up one follower").action(
+      action(async ({ ctx, args }) => {
+        const projectId = requireProject(ctx);
+        const res = await call(ctx, projectId, shape, "profile", {
+          userId: args[0]
+        });
+        ok(res, () => line(JSON.stringify(res?.data ?? res, null, 2)));
+      })
+    );
+  }
 }
 function parseParams(raw) {
   try {
     const parsed = JSON.parse(raw || "{}");
-    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
   } catch {
   }
   throw new Error(
-    `--params must be a JSON object, e.g. --params '{"to":"U123","messages":[{"type":"text","text":"hi"}]}'`
+    `--params must be a JSON object, e.g. --params '{"chat_id":123,"text":"hi"}'`
   );
 }
-async function callLine(ctx, projectId, operation, params) {
-  return api(ctx, `/v1/projects/${projectId}/line/call`, {
+async function call(ctx, projectId, shape, operation, params) {
+  return api(ctx, `/v1/projects/${projectId}/channels/${shape.id}/call`, {
     body: { operation, params }
   });
 }
 function report(res, success2) {
   if (res?.ok === false) {
-    line(import_picocolors23.default.red(res.message ?? "LINE refused that."));
+    line(import_picocolors23.default.red(res.message ?? "That was refused."));
     return;
   }
   line(success2);
@@ -12686,7 +13066,7 @@ function colour(d) {
 
 // src/index.ts
 var pkg = {
-  version: true ? "0.6.28" : "0.0.0-dev"
+  version: true ? "0.6.29" : "0.0.0-dev"
 };
 var program2 = new Command();
 program2.name("workser").description(
@@ -12732,7 +13112,7 @@ registerCheckpoint(program2);
 registerSync(program2);
 registerWorkflow(program2);
 registerConnection(program2);
-registerLine(program2);
+registerChannels(program2);
 registerTool(program2);
 registerMemory(program2);
 registerNote(program2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workser/cli",
-  "version": "0.6.28",
+  "version": "0.6.29",
   "description": "Workser CLI — give your local AI agent native DevOps & infrastructure on Workser. The agent runs `workser …` to provision, deploy, and manage real apps.",
   "license": "MIT",
   "type": "module",

package/skills/workser/SKILL.md

@@ -48,12 +48,9 @@ model call before you have ruled it out. A hand-written one is invisible to the
 Agent Cloud console, unversioned, unmetered, and needs a model credential nothing
 mints — so it answers nobody in production.
 
-It is available on every plan. Creating, configuring and publishing an agent do
-not require a subscription upgrade; a test or live run needs enough prepaid AI
-credits. If a run returns 402, hand the credit top-up to the owner and stop — do
-not quietly build something else. Ruled out for a stated product reason, there
-is an ORDER below it — Claude's managed agents (console.claude.com), Eve,
-LangChain in Python, then hand-built — and you say which rung you took and why.
+Agent Cloud is on every plan. Setup and publish are free; test and live runs need
+prepaid AI credits. On 402, hand over the top-up and stop — do not build a hidden
+substitute. If ruled out for a product reason, follow the ORDER below and say why.
 `workser help agent-cloud` has all of it, including the case that legitimately
 starts lower: a developer wanting their own agent code, knowing this exists.
 

package/skills/workser/reference/agent-cloud.md

@@ -48,6 +48,12 @@ sending it. That matters: the API silently drops unknown fields, so a typo
 would otherwise be accepted, dropped, and reported as success — leaving an
 agent that had been told nothing.
 
+## Nothing starts it until you give it a trigger
+
+A published agent runs when asked and at no other time. A time, a chat message
+or an app event is a **trigger**, and it works the moment it is saved — it is
+not part of the agent's version. `workser help agent-triggers`.
+
 ## Nothing takes effect until you publish
 
 **This is the step to not forget.** The runtime resolves the PUBLISHED version
@@ -193,9 +199,9 @@ watching sees the agent think. See the `workser-sdk` skill, `reference/agents.md
    single biggest cause of an agent that "doesn't work".
 
 3. **Every plan can run agents once the shared wallet has enough credits.** A
-   `402` with `spend_limit_reached` means the wallet needs a top-up (or the owner
-   reached their own spend cap). Tell them exactly what it says and hand over
-   the credit action; never suggest a subscription upgrade for this refusal.
+   `402` with `insufficient_credits` needs a top-up; `spend_limit_reached` means
+   the owner reached the guard rail they set. Tell them exactly what it says and
+   hand over the matching action; never suggest a subscription upgrade.
 
 4. **Say who it is for.** An agent acting for one of the app's customers needs
    `referenceUserId`, or its memory and audit trail belong to nobody.

package/skills/workser/reference/agent-triggers.md

@@ -0,0 +1,69 @@
+---
+topic: agent-triggers
+title: What starts an Agent Cloud agent
+summary: Schedules, chat channels and app events — a trigger works the moment it is saved, unlike everything else on an agent.
+commands: []
+---
+
+# What starts an Agent Cloud agent
+
+A published agent runs when somebody asks it to and at no other time. A trigger
+is what makes it start on its own — a time, a chat message, or an event in a
+connected app.
+
+```
+workser agent-cloud triggers <id>                       # what starts it today
+workser agent-cloud trigger-add <id> schedule cron="0 9 * * 1-5" name="Morning report"
+workser agent-cloud trigger-add <id> chat app_type=line
+workser agent-cloud trigger-add <id> app_event event_type=GMAIL_NEW_GMAIL_MESSAGE connected_account_id=<id>
+workser agent-cloud trigger-setup <id> <triggerId>      # the webhook URL to paste
+workser agent-cloud trigger-events <id>                 # what fired, and what it started
+workser agent-cloud trigger-remove <id> <triggerId>
+```
+
+**A trigger works the moment it is saved** — unlike everything above, it is not
+part of the agent's version and does not wait for a publish.
+
+`rule=` is optional and is the FIRING rule, not the agent's instructions:
+`rule="only when the message mentions an order"`. Leave it empty on a chat
+channel and every message reaches the agent, which is what a support agent
+wants — the agent decides what to do with each one.
+
+For a chat trigger, **`trigger-setup` is not optional**: it returns the webhook
+URL to paste into LINE's or Slack's console, and it says whether anything has
+arrived yet. Without that step the trigger sits there looking finished and
+never receives anything.
+
+To let the agent ANSWER on that channel, the project also needs the account
+connected — `workser line connect --token …`. See `workser help chat-channels`.
+
+## The two halves of a chat agent
+
+Receiving and answering are separate, and each has its own setup:
+
+| | What it does | How |
+| --- | --- | --- |
+| The trigger | a message STARTS the agent | `trigger-add <id> chat app_type=line`, then `trigger-setup` |
+| The connection | the agent can ANSWER | `workser line connect --token …` |
+
+Do only the first and the agent listens and never speaks. Do only the second and
+nothing ever wakes it up.
+
+With both in place, a run started by a message is handed the reply token and the
+sender, and gets every operation of that account as a tool — `line_reply`,
+`slack_send_message` and the rest. Sends go through the agent's approval gate;
+reads do not.
+
+## Schedules, in plain words
+
+`cron=` takes a standard five-field expression. The four people ask for:
+
+```
+cron="0 9 * * 1-5"    every weekday at 9am
+cron="0 9 * * *"      every day at 9am
+cron="0 * * * *"      every hour
+cron="0 9 * * 1"      every Monday at 9am
+```
+
+`timezone=` defaults to UTC, which is almost never what somebody means by "9am".
+Set it: `timezone="Asia/Bangkok"`.

package/skills/workser/reference/chat-channels.md

@@ -0,0 +1,106 @@
+---
+topic: chat-channels
+title: LINE, Telegram, Discord, Slack
+summary: Connect a chat account once, then send, reply and read from the CLI or from an agent — LINE gets its whole Messaging API.
+commands: [line, telegram, discord, slack]
+---
+
+# LINE, Telegram, Discord, Slack
+
+Connect the business's chat account to this project **once**. After that it is
+reachable from here, from Workser Code, and from any Agent Cloud agent in this
+project — including the one a chat message starts.
+
+Every provider takes the same six verbs:
+
+```
+workser <provider> status                       # is anything connected?
+workser <provider> connect --token <token>
+workser <provider> verify                       # does the credential still work?
+workser <provider> disconnect
+workser <provider> ops [--group <name>]         # everything it can do
+workser <provider> call <operation> --params '<json>'
+```
+
+where `<provider>` is `line`, `telegram`, `discord` or `slack`.
+
+## Getting the token
+
+| Provider | Where | Flag |
+| --- | --- | --- |
+| LINE | Developers console → Messaging API → Channel access token | `--token`, plus `--secret` for the channel secret |
+| Telegram | @BotFather → `/newbot` or `/token` | `--token` |
+| Discord | Developer Portal → your app → Bot → Reset Token | `--token` (the bot must also be invited to the server) |
+| Slack | Your app → OAuth & Permissions → Bot User OAuth Token (`xoxb-`) | `--token`, plus `--signing-secret` |
+
+`connect` calls the provider immediately to prove the credential works, so a
+mistyped token fails right there instead of an hour later as a customer message
+nobody answered.
+
+## `call` is the whole API
+
+`ops` prints every operation with a one-line summary. The `●` marks the ones
+that send something, spend quota, or change the account.
+
+```
+workser line call push --params '{"to":"U4af…","messages":[{"type":"text","text":"Your order shipped"}]}'
+workser line call richmenu_list
+workser telegram call send_chat_action --params '{"chat_id":123,"action":"typing"}'
+workser slack call list_conversations --params '{"types":"public_channel"}'
+workser discord call create_thread --params '{"channel_id":"…","message_id":"…","name":"Order #4021"}'
+```
+
+Parameters are flat — path, query and body fields all go in `--params` together
+and the server sorts them. Fields it has never heard of are **forwarded
+untouched**, so a flex component or a Slack block the vendor shipped last week
+works today.
+
+## Shortcuts
+
+```
+workser line send <to> "<text>" | reply <replyToken> "<text>" | broadcast "<text>"
+workser line quota | profile <userId>
+workser telegram send <chatId> "<text>"
+workser discord send <channelId> "<text>"
+workser slack send <channel> "<text>"
+```
+
+## Reply beats push, on LINE
+
+`reply` uses the token that came with the incoming message. It is **free** and
+does not touch the monthly quota; `push` costs one message per recipient. The
+token is single-use and expires within a minute or so, so reply first and fall
+back to push.
+
+`broadcast` sends to every follower and spends one message each. On a large
+account that is the most expensive call available — say what it will cost
+before running it.
+
+## How complete each one is
+
+**LINE is the deep one** — its entire Messaging API, about seventy operations:
+messaging, rich menus, audiences and narrowcast, insight, quota, content,
+groups and rooms, and the webhook endpoint itself.
+
+**Telegram, Discord and Slack carry what a chat agent needs** — send, reply,
+edit, delete, react, typing indicator, threads and DMs, plus reading people and
+conversations. Not their whole APIs. `ops` is the truth; ask it rather than
+assuming an operation exists.
+
+## Rich menus, in order (LINE)
+
+A rich menu does nothing until it has both a picture and a place to appear:
+
+1. `richmenu_create` — the layout and tappable areas. Returns an id.
+2. `richmenu_upload_image` — `content` is the file **base64-encoded**, with
+   `content_type`. The image must match the declared size exactly.
+3. `richmenu_set_default` (everybody) or `richmenu_link_user` (one person).
+
+`richmenu_validate` checks a layout without creating it.
+
+## When it is an agent doing this
+
+An Agent Cloud agent in a project with a connected account gets these as tools
+automatically — there is nothing to bind, and no capability to switch on. Sends
+go through the agent's approval gate; reads do not. See
+`workser help agent-cloud`.

package/skills/workser/reference/line.md

@@ -1,80 +0,0 @@
----
-topic: line
-title: LINE Official Account
-summary: Connect a LINE OA once, then send, reply, broadcast, build rich menus and read insight — from the CLI or from an agent.
-commands: [line]
----
-
-# LINE Official Account
-
-Connect the business's LINE account to this project **once**. After that the same
-account is reachable from here, from Workser Code, and from any Agent Cloud agent
-in this project — including the one a LINE message starts.
-
-```
-workser line status                          # is anything connected?
-workser line connect --token <channelAccessToken> [--secret <channelSecret>]
-workser line verify                          # ask LINE if the token still works
-workser line disconnect
-
-workser line ops [--group messaging|richmenu|audience|insight|people|group|quota|content|account]
-workser line call <operation> --params '<json>'   # any of the 70 operations
-
-workser line send <to> "<text>"              # push to a user, group or room id
-workser line reply <replyToken> "<text>"     # answer a message — free, single-use
-workser line broadcast "<text>"              # EVERY follower, one message each
-workser line quota                           # allowance left this month
-workser line profile <userId>
-```
-
-## Getting the token
-
-LINE Developers console → your Messaging API channel → **Messaging API** tab →
-*Channel access token* (long-lived). `--secret` is the **Basic settings** →
-*Channel secret*, and is only needed if you want LINE's own signature check on
-incoming webhooks.
-
-`connect` calls LINE immediately to prove the token works, so a mistyped token
-fails here rather than an hour later as a customer message nobody answered.
-
-## `call` is the whole API
-
-`ops` prints every operation with a one-line summary. The `●` marks the ones that
-send something, spend quota, or change the account.
-
-```
-workser line call push --params '{"to":"U4af…","messages":[{"type":"text","text":"Your order shipped"}]}'
-workser line call richmenu_list
-workser line call insight_followers --params '{"date":"20260909"}'
-workser line call webhook_endpoint_set --params '{"endpoint":"https://…"}'
-```
-
-Parameters are flat — path, query and body fields all go in `--params` together and
-the server sorts them. Fields it has never heard of are **forwarded to LINE
-untouched**, so a flex component LINE shipped last week works today.
-
-## Reply beats push
-
-`reply` uses the token that came with the incoming message. It is **free** and does
-not touch the monthly quota; `push` costs one message per recipient. The token is
-single-use and expires within a minute or so, so reply first and fall back to push.
-
-`broadcast` sends to every follower and spends one message each. On a large account
-that is the most expensive call in the list — say what it will cost before running it.
-
-## Rich menus, in order
-
-A rich menu does nothing until it has both a picture and a place to appear:
-
-1. `richmenu_create` — the layout and tappable areas. Returns an id.
-2. `richmenu_upload_image` — `content` is the file **base64-encoded**, with
-   `content_type`. The image must match the declared size exactly.
-3. `richmenu_set_default` (everybody) or `richmenu_link_user` (one person).
-
-`richmenu_validate` checks a layout without creating it.
-
-## When it is an agent doing this
-
-An Agent Cloud agent in a project with a connected LINE account gets these as tools
-automatically — there is nothing to bind. Sends go through the agent's approval gate;
-reads do not. See `workser help agent-cloud`.