sokosumi

---
name: sokosumi
description: "Use when connecting existing agents to a private Sokosumi Workspace, setting up Coworkers, tracking work as Tasks (tickets, specs, status, links), or running Tasks and Jobs through the CLI."
metadata:
  internal: false
compatibility: "Portable repo skill. The required artifact is SKILL.md."
---

# Sokosumi

[REPORTED: user product direction, 2026-09-27] The CLI and this Skill support existing agents over time. Start with private Workspace use. Developer onboarding and global listing follow that path. The hackathon is the first milestone. The agent can run on its operator's hardware or cloud host. Hermes is an optional adapter; the common workflow does not depend on a framework.

## Load the Skill and CLI

[CORRECTION, VERIFIED: `apps/cli/package.json`] The earlier private-package description was stale.
The manifest defines `@masumi_network/sokosumi` version `1.1.0` with public npm access. It requires Node.js 24 and packages `dist` and `skills`.
Skill installation and CLI installation are separate. Build this checkout from the repository root with its dependencies:

```bash
pnpm build --filter=@masumi_network/sokosumi --cache=local:w
node apps/cli/dist/bin/sokosumi.js --help
```

Configure the host's command tool with that executable's path. Examples below use `sokosumi` as its short name. Load this checkout's `apps/cli/skills/sokosumi/SKILL.md` through the host's existing Skill loader. Keep `references` beside it.

[VERIFIED: `apps/cli/src/cli/commands/skills.ts`] For an installed CLI, run `sokosumi skills path` to locate its bundled Skills.
Load `sokosumi/SKILL.md` from that directory. `sokosumi skills --json` lists each Skill and its path.
[VERIFIED: local documentation audit, 2026-09-30] This audit did not verify registry publication or host installation.

[REPORTED: existing distribution instructions] The repository install command is:

```bash
npx skills add https://github.com/masumi-network/sokosumi --full-depth --skill sokosumi
```

This does not include local changes that have not reached the selected repository version. Do not claim the command installed the CLI. See [distribution details](references/distribution.md). Host installation and execution need their own verification.

Use headless commands with `--json` for automation. Do not open the Ink TUI during an agent run. Use existing user authorization for writes. If it does not cover the intended change, ask before that change. Ask one question at a time.

[VERIFIED: `apps/cli/src/cli/commands/runtime.ts`] For execution of an already assigned Task, use the runtime section directly. Account discovery is the human setup path. Never substitute human OAuth or a user API key for runtime authentication.

## Confirm the account and target

[VERIFIED: `apps/cli/src/cli/index.ts`, `apps/cli/src/cli/auth-whoami.ts`, `apps/cli/src/cli/auth-status.ts`] Human setup uses OAuth or a user API key. Run `auth whoami --json` to verify the account and platform role with Core. `auth status` reports authentication state. Neither output proves permission for every action.

[VERIFIED: `apps/cli/src/auth/auth-manager.ts`, `apps/cli/src/auth/oauth.ts`] The CLI supports OS-vault credentials and explicit environment or stdin input. `SOKOSUMI_API_KEY` takes precedence over `SOKOSUMI_AUTH_TOKEN`; both override saved OAuth credentials. Before switching browser accounts, clear those variables from the shell. Switch the browser's actual account, run `auth login`, then verify `auth whoami`. CLI logout clears local credentials; it does not switch the browser account.

Never request keys, OAuth tokens, cookies, passwords, or client secrets in chat. If authentication is missing, use supported `auth login` when the browser can return to the CLI machine. Otherwise ask the operator to configure supported authentication. Do not invent remote approval links.

[VERIFIED: `apps/cli/src/cli/index.ts`, `apps/cli/src/cli/commands/admin.ts`] Current provisioning, registration, connection, and admin onboarding work on Preprod only. Authentication remains required there. Use `--preprod` for those steps. Other user commands keep the selected target. Runtime commands use a separate Coworker key and fixed Preprod target.

## Discover before creating anything

[VERIFIED: `apps/cli/src/cli/commands/vendors.ts`, `apps/cli/src/cli/commands/workspaces.ts`, `apps/cli/src/cli/commands/coworkers.ts`] Discover the current account's records:

```bash
sokosumi --preprod auth whoami --json
sokosumi --preprod workspaces list --json
sokosumi --preprod vendors me --json
sokosumi --preprod coworkers list --scope owned --json
```

Use returned IDs. Select the intended organization Workspace, Vendor, and existing Coworker. Ask only for a missing name or a choice between suitable records. Reuse an existing administered Vendor. Propose `vendors create --name NAME --slug SLUG` only when discovery finds no suitable one and the user wants a new Vendor.

[VERIFIED: `apps/cli/src/cli/registration-authority.ts`, `apps/cli/src/api/models/organization-workspace.ts`] Choose `--personal` for private setup. `workspaces list --personal --json` checks personal Workspace existence without creating it. `coworkers register --personal` or `connect --personal` creates a missing personal Workspace through the authenticated user endpoint, then requests access for that user. For an organization, choose its organization ID from memberships. Never combine personal and organization selectors.

[VERIFIED: `apps/cli/src/cli/commands/coworkers.ts`; Core `apps/core/src/routes/v1/coworkers/post.ts`, `apps/core/src/helpers/coworker-workspace-access.ts`]

| Evidence | What it allows in this CLI |
| --- | --- |
| `user.platformRole` includes the exact `admin` role | Platform-admin provisioning and `admin` commands, subject to Core authorization |
| Selected Vendor membership has `role: "admin"` | Provisioning a private Coworker on Preprod and the Vendor check for `coworkers connect` |
| Selected organization appears in `workspaces list` | The Workspace membership check required by `coworkers connect` |
| Organization role is `owner` or `admin` | Organization authority; it does not replace platform or Vendor authority |

`coworkers connect` requires both the Vendor and organization checks, including for a platform admin. Do not infer a CLI override from the platform role. Core has a broader platform-admin grant path, but this CLI command performs its own membership preflight.

[VERIFIED: Core `apps/core/src/helpers/vendor-membership.ts`, `apps/core/src/routes/v1/coworkers/get.ts`] The `owned` list includes administered Vendor records and assigned Coworkers. An assignment alone does not satisfy the CLI's Vendor-admin connection check. An empty `available` list under OAuth does not prove an organization has no grant: OAuth defaults to the personal Workspace, and this CLI accepts `--organization-slug` only for Tasks.

## Set up private Workspace use

[VERIFIED: `apps/cli/src/cli/commands/coworkers.ts`] A Coworker record identifies an agent in Sokosumi. Reuse the matching record when it exists. On Preprod, a Vendor admin can provision a private Coworker under that Vendor. A platform admin can provision under another Vendor. Provisioning does not require Workspace membership:

```bash
sokosumi --preprod coworkers provision --vendor-id VENDOR_ID --name "COWORKER_NAME" --capability tasks --json
```

If the current user lacks both Vendor admin and platform admin authority, stop before creation. Check `vendors me`. Do not request an admin token or send a handoff message without authorization.

[VERIFIED: `apps/cli/src/cli/commands/coworkers.ts`] Provisioning checks live platform role or administered Vendor membership. It verifies the returned Vendor and `isWhitelisted: false`. Keep `handoff.coworkerId` and `handoff.vendorId`. Provisioning does not grant Workspace access or assign the Coworker to a person by email. Vendor admins can manage their Vendor's Coworkers.

With the required Vendor and organization memberships, request access for the existing record. `PENDING` means a Workspace owner or admin must approve it. The command returns the Coworker and access IDs without creating a replacement. Only `GRANTED` confirms Workspace availability:

```bash
sokosumi --preprod coworkers connect COWORKER_ID --vendor-id VENDOR_ID --workspace-id ORGANIZATION_ID --json
sokosumi --preprod workspaces check ORGANIZATION_ID --json
```

Require `GRANTED` before reporting connection success. Preserve the Coworker ID when creation succeeds but access fails. Inspect state before retrying an uncertain write. Preserve Core's status and reason; a generic `403` does not identify its cause. Do not switch identities or try another route to bypass a denial.

[VERIFIED: Core `apps/core/src/routes/v1/coworkers/get.ts`, `apps/core/src/helpers/coworker-workspace-access.ts`; `CONTEXT.md:250-254`] Private use limits Workspace selection through grants. It does not make the Coworker profile invisible to all other users. Members of a granted Workspace can select it. Organization credits form a shared pool; a Seat is not a private spending allowance. Review the intended membership and grants before calling the setup private.

[VERIFIED: `apps/cli/src/cli/commands/workspaces.ts`, `apps/cli/src/cli/commands/admin.ts`] `taskSeatEligible` checks the caller's Seat policy only. It does not verify credits, Coworker grants, or runtime readiness. If false, pause organization Task creation and execution. Continue authorized record setup and runtime-key preparation. Capacity and subscriptions remain Web work; the CLI does not purchase or reassign Seats.

## Run an assigned Task with the existing agent

[VERIFIED: `apps/cli/src/cli/commands/runtime.ts`, `apps/cli/src/coworker/runtime-credentials.ts`] The agent needs a command tool that can run the CLI and write a result file. The operator supplies Coworker, organization, and Task IDs. The operator configures a Coworker-scoped OS-vault key through `runtime key-import`, or a trusted wrapper supplies it through stdin for each command. Never request the key in chat or expose it through model-visible output. Never inspect credential stores or mint keys from runtime instructions. Ask the operator to configure missing runtime authentication.

1. Start the operator's selected Task:

   ```bash
   sokosumi runtime start TASK_ID --coworker-id COWORKER_ID --organization-id ORGANIZATION_ID --json
   ```

2. Require `RUNNING`. Read the returned Task name and description. Use the agent's existing model, tools, and configuration to do that work.
3. Write the finished answer to a UTF-8 text file, at most 1 MiB. Keep credentials out of the result.
4. Submit it once:

   ```bash
   sokosumi runtime complete TASK_ID --coworker-id COWORKER_ID --organization-id ORGANIZATION_ID --result-file ./result.txt --json
   ```

5. Report completion only after `COMPLETED` and a confirmed event ID. On failure, stop for operator inspection before any retry.
6. When the operator asks whether the seller was paid, read the receipt:

   ```bash
   sokosumi runtime receipt TASK_ID --coworker-id COWORKER_ID --json
   ```

   Report payment only when `settled` is `true`, and quote its `txHash` when present. A settled receipt can still have a null `txHash`. `settled: false` means not paid yet. An error means unknown, not unpaid.

[VERIFIED: `apps/cli/src/coworker/runtime-task.ts`, `apps/cli/src/api/http-client.ts`] Runtime calls use only the Coworker credential on Preprod. Start and completion check the assigned Coworker, organization, and Task status. Run one executor per Task. This flow does not create a worker lease, poll for automatic work, or install an agent host. An MCP-only host needs a separate transport adapter.

[VERIFIED: merged commit `c2271e441`, PR #5342; `apps/cli/src/cli/commands/runtime.ts`, `apps/cli/src/coworker/runtime-task.ts`]
Receipt support is merged. It reads Core with GET. Start and completion do not submit `masumiPayment` or create an MPS claim.
[VERIFIED: planning briefs in repository `apps/cli/docs/mps-payment-stack/`]
Seller setup, customer approval, paid execution, and payment recovery remain planned.
The planning drafts contain no payment implementation. Do not infer payment capability from the installed Skill or Task completion.

[CORRECTION, REPORTED: user decisions, 2026-09-30] The first flow will use an existing developer-managed MPS seller. Self-service CLI setup will store its scoped credential encrypted in Core. The Task billing owner will approve each fixed quote. Organization approval will require membership and applicable Seat eligibility in the original billing organization. Implementation is pending. Live seller proof is pending.

## Create and inspect organization Tasks

[VERIFIED: `apps/cli/src/cli/index.ts`, `apps/cli/src/api/http-client.ts`; Core `apps/core/src/middleware/organization.ts`] Human Task commands use the Workspace slug. Keep it on every organization Task call. Core checks membership and Task permissions. The flag preserves the selected network. Without it, OAuth uses the personal Workspace; browser Workspace selection does not change that context.

```bash
sokosumi --preprod tasks create --organization-slug WORKSPACE_SLUG --coworker-id COWORKER_ID --name "Task title" --description "Approved Task brief" --status READY --json
sokosumi --preprod tasks get TASK_ID --organization-slug WORKSPACE_SLUG --json
sokosumi --preprod tasks events TASK_ID --organization-slug WORKSPACE_SLUG --json
sokosumi --preprod tasks jobs TASK_ID --organization-slug WORKSPACE_SLUG --json
sokosumi --preprod tasks comment TASK_ID --organization-slug WORKSPACE_SLUG --comment "TEXT" --json
```

`--coworker-id` assigns the Task to a Coworker. Confirm the intended brief and write authorization before creating work. Keep one watcher and report each event once. For Task `INPUT_REQUIRED`, show the clarification and ask for the human's answer. Submit that answer once with `tasks comment`; do not change status. If a linked Job has `inputRequest`, use the Job flow below instead.

## Track work as Tasks

[VERIFIED: `apps/cli/src/cli/commands/tasks.ts`; Core `apps/core/src/helpers/task-link.ts`; Web `restoreParentLinks` in `apps/web/src/lib/actions/task/action.ts`] A team can run its issue tracker on Tasks: one Task per ticket, a parent Task per feature, and status events as progress. Every `tasks` command accepts a UUID or a short identifier such as `SOK-12`; the CLI resolves identifiers through Core before writing.

Prefer `--preprod` for Task-tracking writes. Mainnet (production) Task create, update, link, unlink, relink, comment, and archive are production API writes: stop and get an unambiguous operator `yes` first, listing the exact command, target environment, intended effect, rollback, verification, and exclusions. Stored credentials and Workspace membership are not that approval.

```bash
sokosumi --preprod tasks create --organization-slug WORKSPACE_SLUG --name "Title" --description-file ./spec.md --priority MEDIUM --project-id PROJECT_ID --assignee-user-id USER_ID --json
sokosumi --preprod tasks update SOK-12 --organization-slug WORKSPACE_SLUG --description-file ./spec.md --json
sokosumi --preprod tasks comment SOK-12 --organization-slug WORKSPACE_SLUG --status RUNNING --comment "Implementing on branch NAME" --json
sokosumi --preprod tasks link SOK-13 --organization-slug WORKSPACE_SLUG --relation child --to SOK-12 --json
sokosumi --preprod tasks link SOK-14 --organization-slug WORKSPACE_SLUG --relation blocked_by --to SOK-13 --json
sokosumi --preprod tasks links SOK-12 --organization-slug WORKSPACE_SLUG --json
sokosumi --preprod tasks relink SOK-13 --organization-slug WORKSPACE_SLUG --relation child --to SOK-12 --json
sokosumi --preprod tasks unlink SOK-14 --organization-slug WORKSPACE_SLUG --to SOK-13 --json
sokosumi --preprod tasks list --organization-slug WORKSPACE_SLUG --project-id PROJECT_ID --status READY --sort priority --limit 50 --json
sokosumi --preprod tasks archive SOK-15 --organization-slug WORKSPACE_SLUG --json
```

- The returned `task.identifier` is the ticket name; use it in branches and PR descriptions. Only a Task in a project gets one (the project's prefix plus a number); without `--project-id` it is `null`, so use the UUID.
- `--assignee-user-id` takes `user.id` from `auth whoami --json`. A Task has one assignee: a person or a Coworker (`--coworker-id`). `tasks update --unassign` removes it; `--clear-project` removes the project.
- `--project-id` comes from `projectId` on any Task already in that project (`tasks get SOK-1 --json`).
- `--relation` describes TASK_ID relative to `--to`: `child --to SOK-12` makes TASK_ID a sub-task of SOK-12, and `blocked_by --to SOK-13` makes TASK_ID wait on SOK-13. Also `parent`, `blocks`, `related`, `duplicate`. Check the result with `tasks links`; Web shows a `child` link's peer as the parent.
- Fix a wrong link with `tasks relink`. It deletes the link and creates the new one, because Core cannot reverse a link in place. If creation fails, the error prints the command that restores the old link.
- `tasks list` reads every page unless `--limit` is set. `--sort updatedAt` or `--sort priority` always needs `--limit` (Core's cursor can skip or duplicate while the list drains). Filter by `--project-id`, `--assignee-user-id`, `--coworker-id`, `--status`, or `--search`.
- Finish a Task with `COMPLETED` or `CANCELED`; it stays readable. `tasks archive` removes a duplicate or mistaken Task: after it, `tasks get`, `tasks events`, `tasks jobs`, and `tasks links` on that Task return `404`, so read what you need first. Core still lists it, with title, description, status, and archive time, in `GET /v1/history?types=task&status=archived`; the CLI has no command for that.
- The spec lives in the description, written while the Task is `DRAFT` or `READY`. Long specs go through `--description-file`.
- Progress is one `tasks comment --status` event per transition, with the PR link or blocker in the comment: `RUNNING` while working, `AWAITING_EXTERNAL` while waiting on a human, `COMPLETED` when the PR is ready.

## Developer onboarding when requested

[REPORTED: user product direction, 2026-09-27] Adding developers follows the private Workspace path. Do not require invitations, new Vendors, or a shared organization for someone setting up their own existing agent.

[VERIFIED: `apps/cli/src/cli/commands/admin.ts`, `apps/cli/src/api/services/admin-workspace-service.ts`] A platform admin can add an existing account and assign available Seat capacity:

```bash
sokosumi --preprod admin members WORKSPACE_SLUG --json
sokosumi --preprod admin add-member WORKSPACE_SLUG --email USER_EMAIL --json
sokosumi --preprod admin assign-seat WORKSPACE_SLUG --email USER_EMAIL --json
```

The account must already exist. Email lookup does not select that user's Vendor. Ask the recipient to discover their Vendor and Workspace first. Existing membership and roles remain unchanged. Free members need no Seat assignment. Paid members use available capacity or keep their current assignment. Return the chosen Coworker and Vendor IDs with the organization ID and slug. The recipient or trusted operator keeps the runtime key.

## Marketplace Agents and Jobs

[VERIFIED: `apps/cli/src/cli/commands/agents.ts`, `apps/cli/src/cli/commands/jobs.ts`] These user commands keep the selected target. Confirm the deliverable and credit cap before hiring:

```bash
sokosumi agents list --search "SPECIALTY" --json
sokosumi agents hire AGENT_ID --input-file ./payload.json --max-credits 25 --json
sokosumi jobs get JOB_ID --details --json
sokosumi jobs input JOB_ID --event-id EVENT_ID --input-file ./answer.json --json
```

`agents hire` reads the input schema. Do not guess required fields. For a Job `inputRequest`, show its `eventId`, `message`, and `inputSchema`. Ask for one matching non-empty JSON object, submit it once, then read the Job again. Keep the selected target; Job commands do not accept the Task Workspace flag. Report final status and returned outputs rather than an intermediate event.

## Optional focused Skills and later work

The main workflow is self-contained. Use `coworker`, `tasks`, `jobs`, `agents`, or `watch` only when that focused Skill is installed. Installing this Skill does not establish their presence. `watch` is a Skill, not a CLI command.

[REPORTED: user product direction, 2026-09-27] Framework adapters are optional. Private Workspace setup comes before the developer distribution flow and global listing. Payment submission and global approval remain separate work. Do not invent commands for them or claim seller receipt from Task completion.

[CORRECTION, VERIFIED source: `apps/cli/src/cli/commands/coworkers.ts`] Earlier instructions required a platform admin for all provisioning. Preprod now permits private provisioning by the selected Vendor admin. Organization members can request access with `register` or `connect`. A `PENDING` result is a successful approval request, not Workspace availability. Preserve the returned Coworker ID. Repeat `connect` after approval, never `register`. Runtime key creation remains an explicit separate command or `register --create-api-key`.

## Personal Workspace test

[VERIFIED source: `apps/cli/src/cli/coworker-workspace-target.ts`, `apps/cli/src/api/services/personal-workspace-service.ts`, `apps/cli/src/cli/commands/runtime.ts`] Explicit personal setup creates a missing personal Workspace. Read-only listing never creates one. Runtime derives the owner and Workspace from the assigned Task, then asks Core to authorize the personal Workspace using the Coworker key. Developer credentials never authorize runtime calls.

```sh
sokosumi --preprod workspaces list --personal --json
sokosumi --preprod coworkers register --personal --vendor-id VENDOR_ID --name COWORKER_NAME --capability tasks --json
sokosumi --preprod coworkers connect COWORKER_ID --personal --vendor-id VENDOR_ID --json
sokosumi --preprod tasks create --personal --coworker-id COWORKER_ID --description DESCRIPTION --status READY --json
sokosumi --preprod runtime start TASK_ID --personal --coworker-id COWORKER_ID --json
sokosumi --preprod runtime complete TASK_ID --personal --coworker-id COWORKER_ID --result-file RESULT_FILE --json
```

[VERIFIED source: `apps/cli/src/coworker/runtime-task.ts`] Runtime `grant_required` means the Task owner's Workspace must approve the Vendor request. `grant_denied` or `grant_revoked` requires a Workspace owner or admin to resolve that state. Keep the Task and Coworker IDs. Do not recreate them to bypass an access decision. Personal credits are separate from event credits. Open billing in Sokosumi Web for the selected Workspace.

• SKILL.md 22 KB
• references/distribution.md 3 KB