@workser/cli 0.6.12 → 0.6.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workser/cli",
-  "version": "0.6.12",
+  "version": "0.6.14",
   "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

@@ -30,7 +30,8 @@ load.
 | Build an automation, or use Gmail/Slack/Stripe/Sheets | `workflow …`, `app …` | `workser help automation` |
 | Generate an image | `image …` | `workser help images` |
 | Hand a subtask to another agent | `agent …` | `workser help roles` |
-| Remember or recall something across conversations | `memory …` | `workser help memory` |
+| Ship an AI agent inside the user's app | `cloud-agent …` | `workser help cloud-agents` |
+| Recall across conversations; leave this task's team a fact | `memory …`, `workser note` | `workser help memory` |
 | Record finished output, or ask the user a question | `artifact …`, `ask` | `workser help deliverables` |
 | Control this machine — files, shell, screen, browser | `tool …` | `workser help computer-use` |
 
@@ -43,7 +44,7 @@ come from the CLI itself, so they match the version you are running.
 workser status                # connection + pinned project + latest deploy
 workser whoami                # who am I / which workspace
 workser project show          # the project pinned to this directory
-workser project list          # the workspace's projects (read)
+workser project list          # your organization's projects
 workser verify                # run typecheck/lint/build — gate "done" on this
 workser doctor                # resolved endpoint, mode, token presence, project
 workser login                 # authenticate outside Orbit (CI/standalone)
@@ -52,24 +53,25 @@ workser logout                # clear a saved standalone session
 
 ## Scope (read this)
 
-You operate on **one project's own infrastructure**. You *can* provision and use it:
-create the Neon database, read its connection string, browse its tables / rows / run
-SQL, provision the bucket + auth, deploy, set env vars, manage files. Sensitive
-actions are **gated** — the daemon may return `error.code = "awaiting_approval"`
-(exit 5); say so, stop, don't loop (rule 5).
+You operate on **a project's own infrastructure**, and you *can* provision and
+use it: database, bucket, auth, deploys, env vars, files. Sensitive actions are
+**gated** (`awaiting_approval`, exit 5) — see rule 5.
 
 What you **cannot** do is administer the project set or destroy config:
 `project create` · `project use` · `env rm` · `domain set` return
 `error.code = "owner_only"` (exit 6). Tell the user it's an owner action to do in
-Orbit, then continue with what you can. The project is already selected; you don't
-pick or switch it.
+Orbit, then continue.
+
+**One organization.** The folder (or the project open in Workser) sets it. You
+may move between its projects — `--project <id>`, or `cd`. Another org
+returns `error.code = "out_of_scope"` (exit 7) and runs nothing.
 
 ## Golden rules
 
 1. **Always pass `--json`.** Output is then a single stable line:
    `{"ok":true,"data":...}` or `{"ok":false,"error":{"code","message",...}}`. Parse it.
 2. **Orient first.** Run `workser status --json` to see the connection, the pinned
-   project, and the latest deploy before acting. You don't pick or switch projects.
+   project, and the latest deploy before acting.
    For anything beyond a trivial edit, also read what the project already knows:
    `workser decision list --json` (what was already decided, so you don't quietly
    reverse it), and `workser design show --json` before writing UI. This project
@@ -80,10 +82,10 @@ pick or switch it.
    `doc create`, plus `decision create` for a real tradeoff. A plan in your
    reply alone is gone when the conversation scrolls. How to correct a wrong
    row, and what not to link: `workser help sdlc-entities`.
-4. **Stay in your lane.** `error.code = "owner_only"` (exit 6) means the action is
-   reserved for the owner in Orbit. Don't retry or look for a workaround — tell the
-   user, then continue. Provisioning the *pinned project's own* db / bucket / auth is
-   allowed (it may be approval-gated, not owner-only).
+4. **Stay in your lane.** On `owner_only` (exit 6) or `out_of_scope` (exit 7),
+   don't retry or look for a workaround — tell the user, then continue.
+   Provisioning the *pinned project's own* db / bucket / auth is allowed (it may
+   be approval-gated, not owner-only).
 5. **Approvals are normal — likely unattended, nobody watching.** An action may
    return `{"error":{"code":"awaiting_approval"}}` (exit 5). Say so, **stop this
    turn** — never a retry loop or sleep-and-recheck, it just times out. Works next

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

@@ -0,0 +1,77 @@
+---
+topic: cloud-agents
+title: Ship an agent inside the app
+summary: Create an AI agent that runs on Workser and can be called from this project's apps.
+commands: [cloud-agent]
+---
+
+# Ship an agent inside the app
+
+`workser cloud-agent` creates an AI agent that runs on **Workser's**
+infrastructure, keeps its own memory and tools, and can be called from the web,
+mobile, API or Python apps in this project.
+
+**This is not `workser agent`.** That one hands a subtask to a coding agent on
+this machine — a teammate helping you build. This one is a thing the project
+*ships*: it works for the user after you are gone.
+
+```
+workser cloud-agent list
+workser cloud-agent create "Order desk" --instructions "..."
+workser cloud-agent show <agentId>
+workser cloud-agent run <agentId> "<what to do>"
+workser cloud-agent runs <agentId>        # recent runs
+workser cloud-agent runs <runId>          # one run, with what it cost
+```
+
+Every call is scoped to the project this folder belongs to.
+
+## When to reach for this
+
+When the user describes a job that **keeps happening** and needs judgement:
+"check every order for stock and email me the problems", "read the LINE
+messages and file them", "reconcile these invoices". That is an agent.
+
+A one-off transformation is not an agent — write the code. A fixed sequence of
+steps with no judgement in it is not an agent either — that is `workser
+workflow`.
+
+## Calling it from the app you are building
+
+Do NOT shell out to the CLI from app code. Use the SDK, which streams:
+
+```ts
+import { workser } from '@workser/app';
+
+const run = await workser.agents.run(agentId, { message }, {
+  referenceUserId: user.id,   // who it is acting for
+});
+
+for await (const event of workser.agents.stream(run.id)) {
+  // event.type, event.data — forward these to the browser
+}
+```
+
+`stream()` reconnects itself through dropped connections, so the person
+watching sees the agent think. See the `workser-sdk` skill, `reference/agents.md`.
+
+## Things that will bite you
+
+1. **A run costs money by the minute.** It is metered — runtime, workspace, and
+   a per-run fee — so a loop that starts agents is a loop that spends. Cancel
+   what you abandon: `workser cloud-agent runs <runId>` shows the cost.
+
+2. **Instructions are the product.** The agent does what its instructions say,
+   in the user's own words. Write them the way you would brief a new colleague:
+   what to do, what to leave alone, when to ask. Vague instructions are the
+   single biggest cause of an agent that "doesn't work".
+
+3. **Free plans cannot run agents at all**, and a trial has a small allowance.
+   A `402` with `spend_limit_reached` is not a bug — tell the user what it says
+   and point them at their plan.
+
+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.