@kosuke-ai/kosuke 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+## 1.0.1
+
+- Allocate package versions when publishing and collect changes from separate PR fragments.
+- Add `setup status` and `setup repair` for hidden setup runs and their bounded repairs. `preview get` without `--session-id` answers 410 `NO_MAIN_PREVIEW`: a project keeps no main sandbox any more.
+- Add `personal-tasks list`, `create`, `get`, `update`, `delete` and `move`: the member's own tasks, in no workspace, which Sensei files from a thread. `personal-tasks update` takes `--if-revision` to refuse a description saved over a newer one, and `personal-tasks move` turns a Todo or In progress one into a workspace's Todo task.
+- Add `user files list|get|put|mkdir|move|delete` for your personal Files, which belong to you and to no workspace. An agent reaches those of the member it acts as and never deletes.
+- Remove `workspaces integrations slack get`: the Slack Bot is retired, and its endpoint answers 410. Personal Slack stays under `user integrations list`.
+- Require an explicit workspace member for proposals and message reroutes.
+- Keep the task Overview and Recently done reads restricted to the web app.
+- Sensei picks up a site's sign-in from the member's everyday Chrome by itself, with no tap, once per site and profile in a Turn the member's own message started: `mac browser-sign-in --reuse` never opens Chrome and answers `chrome` `none`, `same` or `different` with `taken`. `mac browser-profiles --site <host>` says per profile whether it is allowed or off (`access`) and, for each allowed profile, whether Chrome holds a candidate sign-in for that site (`chromeSignIn`), from cookie presence only.
+- `tasks update` takes `--status archived` to archive a task, and `--hint-project` to file a Todo task with no repository in a Collaboration project without starting it. `tasks list` and `tasks all` take `--status archived`, and list every status by default.
+- Keep platform-wide command search browser-only while preserving the CLI session search contract.
+- Add --next-turn to sessions update and tasks update, to choose the Model, or Auto, a started session's next Turn runs on.
+- Start Personal tasks in a Personal Repository while preserving their identity through Start and Move.
+- Add `kosuke user crons list|get|create|update|run|runs list|runs get` for your Personal Crons, each running its prompt as your message in its own Sensei Thread on your own Subscription, with its own `--timezone`. From your Sensei, `user crons create` answers 409 `CRON_ALREADY_EXISTS` when you already have a Personal Cron by that name. `kosuke projects create --personal` now also works from your Sensei in a Turn you started.
+- Remove task and session comment commands; task comments no longer exist.
+- Start tasks with an optional technical prompt while keeping their saved descriptions unchanged.
+- Document the new limit of 20 personal subscription keys per provider; Google keeps one key per method.
+- `sessions app-stack-start` answers a retryable 409 `APP_STACK_NOT_READY` while the session's sandbox is still setting up and 409 `APP_STACK_STARTING` while another start runs, and `sessions get` reports `appStackState` and `appStackError`, so a failed start reads as failed for everyone.
+- Remove Build Macs: `build-mac connect|status|disconnect|run|list|remove|setup-token` are gone, and the desktop helper no longer ships in the package. `tasks create|update|start` and `sessions create|update` lose `--runs-in` and `--build-mac-id`: every session runs in a sandbox, and its Linux desktop starts when its Desktop tab first opens.
+- Add `--sandbox-size small|medium|large|xlarge` and `--app-stack start|skip` to `tasks create|update|start` and `sessions create|update`: a task's session boots on that size, and with `skip` without the project's services. `tasks update --hint-project` picks the repository of a task with no session. Size and stack are fixed once the session starts (409 `SANDBOX_SETTINGS_LOCKED`). New `sessions app-stack-start` starts a skipped App stack and waits until its services answer.
+- Add `devices list` and `devices request <deviceId> --reason`, with which a Chat Session's agent asks to test on its workspace's devices or its member's own Macs. Once an approver allows it for the session, the `mac` screen, input, `open`, `shell` and file commands take `--device-id` from a session too; the browser commands stay Sensei's.
+- `kosuke sensei reels proposals` lists Backlog tickets newest first by creation or edit, no longer ranked by Jev.
+- Remove `setup status` and `setup repair`: the hidden setup run is rolled back, and the deploy agent keeps a main sandbox again. `preview get` without `--session-id` answers for the main sandbox again instead of 410 `NO_MAIN_PREVIEW`. `sessions watch` on a Deploy links only to its Deploy Chat, with no preview link.
+- Add `sensei device-requests list` and `sensei device-requests decide`: a member's Sensei reads a Chat Session's device requests and approves or declines one as them, refused with 409 `GRANT_ALREADY_DECIDED` and the request's current status once it is no longer pending.
+- Update the CLI test dependencies to patched Vite and Vitest releases.
+- LinkedIn and X are browser integrations. `kosuke integrations list` shows them as `browser, no tools`, with one line per connection, also with `--toolkit` and `--account`. Sensei reads its member's connections with `kosuke mac browser-connections [--site]` and reports a check with `kosuke mac browser-connection-check`; members list, connect and reconnect them with `kosuke user integrations linkedin|x list|connect|reconnect`.
+- `kosuke integrations call --help` no longer ties its 330 s wait to a call on the member's Mac.
+- Add members list to read visible members across your workspaces, with an optional workspace filter.
+- Add `sensei delegates start`, `get`, `note` and `stop`: in a member's Turn, Sensei hands a long job to a Job Delegate, reads a delegate and its newest unread result, delivers a change of the member's intent as a Note, and stops a delegate.
+- Add `kosuke sensei thread handoff`, which hands work the member asks for in Sensei's Main Chat to a new thread.
+- `user subscriptions token-usage` and `workspaces ai-provider token-usage` read the tokens Kosuke spent on your own Subscriptions or on the workspace's Credentials (owners and admins only), per Provider and per account, over the last 7 days, the last 30 days and everything recorded, with input, cache read, cache write and output kept apart, how many runs reported no counts, and on your own usage the Sensei share.
+- Add `kosuke sensei threads` so Sensei lists the member's threads when it needs them.
+- Allow workspace Crons to save and run without repositories, expose each run's kind, and preserve the No projects left refusal until a repository is selected.
+- Let Personal Crons pick Personal Repositories and Apps, run in their own sandbox, and read their run Artifacts.
+- Filter tasks and sessions by label and list the label names available across a workspace's repositories with tasks labels.
+- Accept the explicit Kosuke free model choice for personal Crons.
+- Personal tasks can explicitly choose Kosuke free beside connected subscriptions, including unlinked tasks and queued Next Turn choices. Personal task model fields accept kosuke-free; Next Turn choices accept {kosukeFree:true} only in personal scope. The personal Default Model accepts kosuke-free, Sensei views expose the persisted source and personal Auto choice, and access status keeps Free routing details private.
+- Check attachment counts and sizes against the limits the platform publishes for each command, so the CLI never refuses a batch the platform accepts or sends one it refuses.
+- Update XLarge Sandbox size descriptions to 16 CPU and 32 GB of memory.
+- Remove `kosuke sensei thread handoff`: Sensei has no Main Chat, and every message from the main composer starts a thread of its own.
+- Add approved reply and conversation FYI mark-read card commands
+- Add covers to sensei cards put, naming the incoming messages a card answers; an FYI update keeps the committed coverage of its open card across updates, and the open FYI keeps a reference to every message it covered, which its Mark read marks
+- Register personal message Watching as a web-only setting without exposing agent or API-key controls
+- After a Sign in with Chrome tap, the Mac watches every site for the sign-in to land, not only LinkedIn and X: on another site it takes the site's cookies once they change and answers `taken: true` with `signedIn: false`, or `taken: false` when nothing changed, so Sensei checks the account in its own browser before going on. `mac browser-sign-in --wait-new` now accepts any site, with `--url` too, and may follow every take that left the site signed out, while the answer's `waitNewLeft` allows: up to 6 per tap, within 9 minutes of it, after which it answers `SIGN_IN_WINDOW_ENDED`. A follow-up never opens a second tab for a site the Turn already opened.
+- Add `kosuke projects batch-merging get`, `set`, `eject` and `finish` for Batch Merging.
+- `kosuke projects batch-merging set` refuses to turn Batch Merging on while the repository allows no merge commit, and `get` says whether one can land.
+- Remove `kosuke proposals create` and its aliases. `kosuke sensei messages send` now works for every sender, with an optional session, pull request and link.
+- Support personal Job result targets on Sensei cards.
+- Add `kosuke sessions qa set` and `kosuke sessions qa clear`, which record the commit QA passed on. `kosuke sessions get` and `list` return it as `qaPassedSha`, with `batchEjections`.
+- Include every released provider in agent summaries and personal Cron models, report holdsSubscription and autoAvailable in `user subscriptions get`, and drop the personal Gemini API key and Google method commands: personal Google access is the Antigravity sign-in only.
+- Expose waitingForDeploy on session reads and lists while a session waits for a Deploy to finish.
+- Add --report-to to crons create and update: the members a workspace Cron's messages go to.
+- `kosuke workspaces ai-provider set` accepts the `default_auto` operation, which makes Auto the Workspace Default Model.
+- `kosuke sensei merge` merges the pull request of any Chat Session in a workspace you belong to, as you, not only one you are assigned.
+- Offer notifications once in Sensei's iPhone onboarding chat and bind push registration to its Connect attempt.
+- Require approval Cards for Sensei WhatsApp replies, including messages without a Watching event.
+- Add `--name` to `kosuke sensei delegates start`, a short name the Sensei crew list shows for the job.
+- Publish the CLI as @kosuke-ai/kosuke and give the private desktop workspace its own package name.
+- List restricted personal integrations with an explicit availability marker and no held connections.

package/README.md

@@ -1,3 +1,200 @@
 # @kosuke-ai/kosuke
 
-The Kosuke CLI. The first full release is coming soon. Until then, use @kosuke-ai/cli.
+The Kosuke platform CLI: `kosuke`, the client you install on your own machine to
+drive [app.kosuke.ai](https://app.kosuke.ai). Not `ksb`, the agent that
+runs inside a Kosuke sandbox: that one lives in `sandbox/ksb-cli` and is
+installed inside sandboxes alongside this platform CLI, never by hand.
+
+```sh
+npm install -g @kosuke-ai/kosuke
+kosuke auth login          # paste an API key from Settings
+kosuke projects list | jq '.data[] | {id, name}'
+kosuke sessions create <projectId> --title "Fix the login form" \
+  --content "See the screenshot" --status backlog --attach shot.png
+kosuke crons create <workspaceId> --project <projectId> --project <projectId> \
+  --name "Daily ingest" --prompt "/sources" \
+  --cron-expression "0 6 * * *"
+kosuke workspaces timezone-set <workspaceId> --timezone Europe/Zurich
+```
+
+Every API command prints the platform's JSON response as is, so it pipes into `jq`.
+Path params are positional, request fields are flags (`--exclude-archived`,
+`--start-line-number 12`, and `--project a --project b` where a field takes
+several values), and any body can be passed whole with `--body '{…}'`,
+`--body-file path` or `--body-file -` for stdin. `kosuke <group> --help` lists
+the operations; each one's help is the API's own description.
+
+The API key comes from `--api-key`, then `KOSUKE_API_KEY`, then the file
+`kosuke auth login` writes (mode 0600, under `~/.config/kosuke`, or
+`KOSUKE_CONFIG_DIR`). `--api-url` / `KOSUKE_API_URL` point it at another
+deployment.
+
+## Factory Skill markers
+
+The main chat agent records Factory Skill boundaries with these commands:
+
+```sh
+kosuke sessions skill-runs start kosuke:ship --no-review
+kosuke sessions skill-runs end kosuke:ship --result ready
+```
+
+The sandbox supplies the session identity and its Turn credential. The server selects the
+running Chat Job. These commands accept only known switch names and result values, never
+free text. A child skill starts inside its parent and ends before the parent resumes.
+
+Markers are best effort: one request, a 1.5-second deadline, no retry, and exit status zero
+even for invalid input or a tracking failure. They print no success message. Without the
+main-agent marker context, they send no request. Delegated Runs do not record markers.
+Other commands keep their normal error exit codes. `sessions skill-runs --capabilities`
+prints `skill-markers-v1` without credentials, so an older CLI never receives an unsupported rule.
+
+## Watching a turn
+
+`kosuke sessions watch` follows one turn's job as it runs, so a script does not
+have to poll `sessions jobs get`. Each frame the platform streams is one JSON
+line on stdout, so it pipes into `jq`, and everything meant for a person goes to
+stderr. The job id is the `chatJobId` that `sessions create` and `sessions send`
+return.
+
+```sh
+kosuke sessions watch <projectId> <sessionId> <jobId> \
+  | jq -r 'select(.type == "message") | .data.text'
+```
+
+A dropped connection picks up after the last frame it delivered. The job's
+status is read every 5 seconds alongside the stream, so a stream that goes quiet
+still ends; when the status is what ended it, a `watch.status` frame says which.
+When the status says the job ended, a dropped stream is reconnected until it has
+replayed what it holds, within `--timeout`, or 15 seconds without one. If it still
+could not be read to its end, that frame's `complete` is `false`: frames may be
+missing. The exit code still follows the job, so a completed job exits 0 even
+then; a script that needs every frame checks `complete`.
+Once the job has ended, a last `watch.links` frame carries the session, preview
+and pull request links. `--timeout <seconds>` bounds the wait. The command exits
+0 when the job ended well, 1 when it failed or was stopped, 3 when the API key
+was refused, 4 when the project, session or job was not found, and 124 when
+`--timeout` passed first.
+
+`--type deploy` watches a deploy instead. The job id is then the
+`activeStreamId` that `kosuke deploy messages` returns, and the session id is
+not read. The deploy's status describes its latest turn only, so when a later
+turn or Deploy takes over before the watch reads how this turn ended, it says
+so on stderr and exits 1.
+
+This command is written by hand: the stream is a WebSocket, which the OpenAPI
+document below cannot describe.
+
+## Upgrading from 5.x
+
+A cron no longer has a timezone of its own: every cron of a workspace is read
+in the Workspace Timezone, which `kosuke workspaces timezone-set <workspaceId>
+--timezone Europe/Zurich` sets, as an owner or admin. `crons create` and `crons
+update` lose `--timezone`, and the API refuses a cron body that still sends one,
+which is what an older CLI does with `--timezone`. `crons get` still prints the
+cron's `timezone`, the workspace's.
+
+## Upgrading from 4.x
+
+A cron now belongs to its workspace and covers one or more projects, so every
+`crons` command takes `<workspaceId>` where it took `<projectId>`: `kosuke crons
+get <workspaceId> <cronId>`. `crons create` names its projects with a repeated
+`--project`, and `crons update --project` replaces them. `crons run` fires every
+project that is not paused, or only those named with `--project`. `crons runs
+list` filters with `--project` and `--status`, each repeatable. `crons projects
+resume <workspaceId> <cronId> <projectId>` resumes one project that five failed
+runs in a row paused. An older CLI answers 404 on every `crons` command.
+
+## Upgrading from 1.x
+
+The review comments on the diff moved to `sessions diff comments list|add|update|delete`, beside
+`sessions diff files` and `sessions diff patch`, whose route they share.
+
+## Nightly builds
+
+The `next` dist-tag tracks the CLI version stage runs. A pull request that changes
+shipped CLI code adds a new `changelog.d/<unique-slug>.json` fragment covering `cli`,
+without editing package versions or `CHANGELOG.md`. Publication computes the next
+patch above the highest published version and assembles the fragments, so the CLI
+can be as new as stage without waiting for a platform release:
+
+```sh
+npm install -g @kosuke-ai/kosuke@next
+```
+
+`next` is a moving tag: the same command updates. `npm install -g
+@kosuke-ai/kosuke` installs `latest`, which a platform release moves onto the
+version it deploys, so the plain install always matches production.
+
+`kosuke auth login` writes the API key, and the API URL when it is not the
+default, into one `credentials.json` that replaces whatever was there, so a
+config directory holds exactly one deployment and logging into stage would
+overwrite a production login. Give stage its own directory, and keep
+`KOSUKE_CONFIG_DIR` exported for every `kosuke` call meant for stage: a new
+shell without it is silently back on production.
+
+```sh
+export KOSUKE_CONFIG_DIR=~/.config/kosuke-stage
+kosuke auth login --api-url https://app.stage.kosuke.ai
+kosuke projects list    # same shell, so it reads the stage key and URL
+```
+
+A shell alias or direnv keeps the variable set; `kosuke auth status` prints
+which URL, which key source and which credentials file won.
+
+## A digest for an agent
+
+`kosuke agent summary` prints the sessions that need you and your oldest New
+Activity events across every workspace, one line each, and the name of every
+workspace it read, in about 1,500 tokens. It lists only as many events as the
+rest leaves room for, so fewer when you belong to many workspaces, and marks
+seen only the events it prints. The rest stay New for
+`kosuke activity list --unseen`. `--workspace <id>` reads that one workspace
+alone, in both the sessions and the events, and the commands it names for the
+rest carry the same flag; with it, or inside an agent's turn, the digest also
+lists the connected integrations, one line each. `--peek` prints the same
+events and marks none seen, for an agent that reads the digest before every
+answer.
+
+## Integrations
+
+`kosuke integrations` lists, describes and runs the tools of the integrations
+connected to a workspace, and to you.
+
+```sh
+kosuke integrations list --workspace <id>                    # a block per toolkit
+kosuke integrations list --workspace <id> --toolkit gmail    # that toolkit's tools
+kosuke integrations describe <tool> --workspace <id>         # one tool's input schema
+kosuke integrations call <tool> --workspace <id> --account notion-personal --args '{"query":"roadmap"}'
+```
+
+`list` with no filter prints each toolkit's connections (alias, scope, label,
+account, short id) and how many read-only and write tools it has. `--toolkit` and
+`--search` list the matching tools, and a list that is cut short says "N of M"
+and how to narrow it. `--account` takes a connection's alias such as
+`notion-personal`, its short id or `scope:label`; case, curly quotes and extra
+spaces do not matter, and it is needed when several connections can run a tool.
+`call` prints the tool's text on stdout and the connection it ran on on stderr,
+and exits 1 when the tool reports an error.
+
+With an API key, `--workspace` is required (you must belong to it), and `call`
+runs only your own personal connections. Inside an agent's turn the credential
+decides the workspace and the flag is optional. A Connector Token is refused.
+`kosuke integrations tools` and `execute` print the raw JSON of the same two
+routes. `kosuke agent summary` lists the same connections, one line each.
+
+## Generated from the API
+
+`openapi.json` is the platform's own `GET /api/openapi.json`, snapshotted by
+`bun run openapi:snapshot` at the repository root. `npm run generate` turns it
+into `src/generated/`: request types (openapi-typescript) and one descriptor per
+operation, which the hand-written runtime turns into commands. `npm run check`
+regenerates and fails on any difference, so the tree is only ever what the
+document says.
+
+## MCP server
+
+Kosuke is served to an MCP client at `https://app.kosuke.ai/api/mcp`; sign in
+once in the browser to authorize a client and the credential renews itself,
+so there is nothing to install or run here. See
+[the docs](https://docs.kosuke.ai/interfaces/mcp) for adding it to Claude,
+ChatGPT, Codex or Cursor.

package/dist/agent/http.js

@@ -0,0 +1,18 @@
+/** The sessions that need the member themselves. */
+export const NEEDS_YOU_FILTER = {
+    needsYou: true,
+    owners: 'me',
+};
+export class HttpError extends Error {
+    status;
+    constructor(status) {
+        super(`HTTP ${status}`);
+        this.status = status;
+    }
+}
+/** `meta.pagination.total` of a list envelope, or null when the body is not one. */
+export function paginationTotal(body) {
+    const total = body?.meta?.pagination
+        ?.total;
+    return typeof total === 'number' && Number.isFinite(total) ? total : null;
+}