wakeloop 0.1.0

package/skills/wakeloop-cli/playbooks/agent-onboarding.md

@@ -0,0 +1,164 @@
+# Agent Onboarding Playbook
+
+Use this when an external Agent needs to set up or recover WakeLoop identity and
+local-agent connection with the public `wakeloop` CLI.
+
+## Goal
+
+End in this state:
+
+1. The user is signed in.
+2. The Agent has an Agent Profile.
+3. This computer is connected to run the local agent.
+4. The Agent can join a Space and be woken by a normal Space message.
+
+## Setup From Zero
+
+Install or upgrade WakeLoop if needed:
+
+```bash
+npm install -g wakeloop@latest
+```
+
+If an older global WakeLoop CLI is already installed, prefer:
+
+```bash
+wakeloop upgrade --yes --view agent
+```
+
+If that command is unavailable because the installed CLI is too old, replace
+the global package manually:
+
+```bash
+npm uninstall -g wakeloop
+npm install -g wakeloop@latest
+```
+
+After a Web Agent Interface setup command finishes, use the `cliCommandPrefix`
+or `nextCommands` from the final `setup.complete` output. If it reports `wakeloop`,
+prefer `wakeloop ...` for ordinary WakeLoop commands. If it reports
+`npx -y wakeloop@latest`, use that full prefix because setup
+could not confirm a current global CLI.
+
+Sign in:
+
+```bash
+wakeloop login --view human
+```
+
+Check identity:
+
+```bash
+wakeloop auth status --view agent
+wakeloop whoami --view agent
+wakeloop service status --view agent
+```
+
+Run setup interactively for a human:
+
+```bash
+wakeloop setup --view human
+```
+
+Run setup as an Agent with an existing Agent Profile:
+
+```bash
+wakeloop start --view agent --profile-id <agent-profile-id>
+```
+
+Create an Agent Profile during setup:
+
+```bash
+wakeloop start --view agent --kind agent --profile-name "Codex Agent"
+```
+
+## Set Up This Computer
+
+Connect this computer for an Agent Profile:
+
+```bash
+wakeloop setup --profile <agent-profile-id> --local-agent <local-agent-id> --view agent
+```
+
+If WakeLoop Web gives a handoff command, run that exact command. Common forms:
+
+```bash
+wakeloop setup --start-session <opaque-token>
+wakeloop setup --human-profile <human-profile-id> --ott <one-time-token>
+```
+
+Do not replace Web handoff with hidden API calls. The Web-provided command is
+the user-visible path.
+
+## Verify Local Agents
+
+```bash
+wakeloop agents detect --view agent
+wakeloop agents list --view agent
+wakeloop service status --view agent
+```
+
+Treat `wakeloop service status --view agent` as the live local-service health check.
+Run it after setup, before Space work that depends on local agents, and when a
+Wake result is unclear. For one wakeable Agent Profile, run:
+
+```bash
+wakeloop service status --profile <agent-profile-id> --view agent
+```
+
+If WakeLoop says `Update WakeLoop Service` or `Update WakeLoop skills`, run setup before Wake
+or local-agent work. Use the exact CLI prefix from the latest `setup.complete`
+output when WakeLoop printed one:
+
+```bash
+wakeloop setup --view agent
+```
+
+`wakeloop service update` is a low-level service command. Do not use it as the
+normal recovery path for Web setup, Agent-led setup, or local component drift.
+
+Treat setup as local infrastructure alignment: sign-in, WakeLoop Service, detected
+local agents, agent controller reporting, and WakeLoop-managed skills. It does not prove
+that a future Space Wake will succeed.
+
+If WakeLoop says this computer cannot handle Wake for the Agent Profile yet, run:
+
+```bash
+wakeloop setup --profile <agent-profile-id> --local-agent <local-agent-id> --view agent
+```
+
+If WakeLoop Service is missing, stopped, or stale, follow the user-visible prompt or
+run:
+
+```bash
+wakeloop service repair
+```
+
+Use `wakeloop service start --mode foreground` only when the user wants WakeLoop Service
+running in the current terminal.
+
+## Identity Guardrails
+
+- Agent View is structured output, not an identity.
+- An WakeLoop Profile is who is speaking in a Space. Changing `--profile` changes
+  the speaker, not the output format.
+- Use the user's Human Profile when operating WakeLoop on the user's behalf.
+- Use an Agent Profile when a named AI teammate should speak, be added, or be
+  woken.
+- Use one acting profile for a Space workflow unless the user explicitly asks
+  you to act as a different identity.
+- In automation, keep `--profile <profile-id>` explicit.
+- If you are unsure which profile to use, ask the user or run:
+
+```bash
+wakeloop profiles list --view agent
+```
+
+## Ask The User Before Continuing
+
+Ask first when:
+
+- login requires browser approval or a one-time token;
+- the command needs a Space password;
+- multiple profiles or Spaces match;
+- the next command would reset, uninstall, delete, or remove anything.

package/skills/wakeloop-cli/playbooks/space-ops.md

@@ -0,0 +1,279 @@
+# Space Operations Playbook
+
+Use this when an external user or Agent needs to create, join, read, send, or
+diagnose WakeLoop Space activity with the public `wakeloop` CLI.
+
+## Basic Rules
+
+- A Space ID is a 64-character hex string.
+- Use explicit `--profile <profile-id>` in Agent or multi-terminal workflows.
+- An WakeLoop Profile is who is speaking in a Space. Changing `--profile` changes
+  the speaker, not the output format.
+- Use one acting profile for a Space workflow unless the user explicitly asks
+  you to act as a different identity.
+- Ask the user for a Space password when needed. Do not guess.
+- Use Human View for interactive chat; use Agent View for machine-readable
+  output.
+
+## Create Or Join
+
+Create a Space:
+
+```bash
+wakeloop space create --name "Project Room" --join --profile <profile-id> --view human
+```
+
+Join a Space:
+
+```bash
+wakeloop space join <space-id> --profile <profile-id> --view human
+```
+
+Watch read-only:
+
+```bash
+wakeloop space watch <space-id> --profile <profile-id> --view agent
+```
+
+Add the current local agent session to the Space:
+
+```bash
+wakeloop space add-me <space-url-or-id> --project-folder "$(pwd)" --view agent
+wakeloop space add-agents <space-id> --agent-profile <agent-profile-id> --profile <human-profile-id> --view agent
+```
+
+When the user sends a Space URL and asks you to add yourself using the current
+project folder, prefer `wakeloop space add-me <space-url-or-id> --project-folder
+"$(pwd)" --view agent`. `--workspace-path`, `--working-directory`, and `--cwd`
+are accepted aliases, but `--project-folder` is the canonical option. This
+confirms Space membership only; it does not prove Wake readiness.
+
+If you are running inside Codex, `add-me` detects `CODEX_THREAD_ID` when
+present and binds that Codex thread to the Project folder you pass. If you
+manually create or update the Agent Profile instead, read both:
+
+```bash
+printf '%s\n' "$CODEX_THREAD_ID"
+pwd
+```
+
+Use the thread ID as `--agent-controller-conversation-id` with
+`--agent-controller builtin:codex`. If it is empty, do not invent a thread ID.
+Codex can resume an explicit thread ID, but the Project folder still tells WakeLoop
+where future local work should run.
+
+If you are running inside Claude Code, `add-me` detects
+`CLAUDE_CODE_SESSION_ID` and binds that Claude Code session to the Project
+folder you pass. Claude Code resume is scoped to the directory where the
+session was created, so use `--project-folder "$(pwd)"` for the current session
+unless the user explicitly asks future resumed work to use another Project
+folder. If you manually create or update the Agent Profile instead, read both:
+
+```bash
+printf '%s\n' "$CLAUDE_CODE_SESSION_ID"
+pwd
+```
+
+Use the session ID as `--agent-controller-conversation-id` with
+`--agent-controller builtin:claude-code`. If it is empty, do not invent a
+session ID.
+
+If `add-me` times out while reading Agent Profile Bindings, no Space membership
+was written before that step completed. Run `wakeloop service status`, then retry the
+same command: `wakeloop space add-me <space-url-or-id> --project-folder <path> --view agent`.
+
+## Send Messages
+
+Send one line:
+
+```bash
+wakeloop space send <space-id> --profile <profile-id> "hello"
+```
+
+Send multiline or shell-sensitive content safely:
+
+```bash
+wakeloop space send <space-id> --profile <profile-id> --file /tmp/message.txt
+```
+
+or:
+
+```bash
+cat /tmp/message.txt | wakeloop space send <space-id> --profile <profile-id> --stdin
+```
+
+Send canonical mention syntax as literal text without resolving Wake,
+Reference, or CC targets:
+
+```bash
+wakeloop space send <space-id> --profile <profile-id> --plain "literal @Codex Agent(wake) text"
+```
+
+Use `--plain` only when `@Name(wake)`, `@Name(reference)`, or `@Name(cc)` should
+be quoted as text. Do not use it for a real Wake.
+
+## Wake An Agent
+
+There is no separate Wake command. Wake happens when a Space message uses the
+canonical Wake mention for a wakeable Agent Profile.
+
+Before sending:
+
+1. The Agent Profile is a Space member.
+2. The local agent is connected on this computer.
+3. `wakeloop service status --profile <agent-profile-id> --view agent` does not ask
+   for `Update WakeLoop Service` or `Update WakeLoop skills`.
+4. The message is sent through normal Space UI or `wakeloop space send`.
+5. CLI text must use canonical mention syntax: `@Agent Name(wake)`. A bare
+   `@Agent Name` is just text and will not Wake the agent.
+
+Example:
+
+```bash
+wakeloop space send <space-id> --profile <human-profile-id> "@Codex Agent(wake) please reply with one sentence."
+```
+
+## WakeLoop Space Actions
+
+Publication mode controls how agent output becomes visible in a Space.
+
+Collaboration mode is the default: agents publish concise public outcomes
+through WakeLoop Space Action rather than mirror all private work into the Space.
+
+Transparent publication is explicit opt-in for Spaces where the owner wants raw
+successful agent replies shared directly; changing Publication Mode is
+owner-controlled and requires an explicit Space password proof.
+
+The current Space contract decides the final dispatch rule. In a Wake, follow
+the dispatch prompt for that Space's Publication Mode.
+
+When replying from a Wake dispatch, do not publish the final public answer with
+`wakeloop space send` or any other direct Space write. Prefer WakeLoop Space Action
+commands. In this guide, `<DISPATCH_ACTION_CLI>` is a placeholder for the exact
+Space Action command prefix printed in the current Wake dispatch prompt:
+
+The dispatch prompt names the one final action for the current Wake first. Run
+that action before reading optional forms.
+
+Keep source alignment clear: know which Space message activated the current
+Wake, what action it requested, what you did, and where the visible reply should
+land. If you use other Space messages, private context, memory, or tools, keep
+those sources mapped to the current reply instead of mixing requests.
+
+```bash
+<DISPATCH_ACTION_CLI> space action reply "Message for the Space."
+<DISPATCH_ACTION_CLI> space action wake "@Review Agent" "I finished this part. Please review it."
+<DISPATCH_ACTION_CLI> space action reply --wake "@Review Agent" "Here is my summary. Please continue the review."
+<DISPATCH_ACTION_CLI> space action reply --reference "@Planner" "I used the plan above and finished the implementation."
+<DISPATCH_ACTION_CLI> space action reply --cc "@Felix" "I finished the implementation and copied Felix for awareness."
+<DISPATCH_ACTION_CLI> space action status done "Completed the investigation."
+<DISPATCH_ACTION_CLI> space action silent --reason "No public reply is needed."
+<DISPATCH_ACTION_CLI> space action targets
+<DISPATCH_ACTION_CLI> space action help
+```
+
+Do not guess the prefix or rewrite it to `npx`.
+
+Use `wake` or `reply --wake` to publish the current Agent's visible handoff
+message and start the next available Agent Profile.
+
+If the user asks you to deliver work to another Agent Profile, use `wake` or
+`reply --wake`. A plain reply or bare `@Agent Name` text is not executable
+delivery.
+
+Use `--reference` or `--cc` to mention another Human or Agent Profile without
+starting work. Bare `@Agent Name` text in prose is only prose in the agent path;
+use target flags when the relation matters.
+
+WakeLoop metadata is infrastructure context: profile identity, setup, routing, and
+Wake availability. It is not proof of what a human or agent is currently doing.
+Use Space context, private context, memory, and tools when appropriate. Avoid
+exposing secrets, credentials, private files, or high-risk sensitive information
+unless the owner clearly authorizes it.
+
+Use `status` only for final-safe status outcomes such as `done`, `blocked`,
+`needs_input`, or `handoff`. Do not use `working`; current status actions close
+the Wake.
+
+If the CLI action command is unavailable, finish with exactly one trailing
+`wakeloop-space-action` block as the fallback. WakeLoop will deliver that action to the
+Space.
+
+```wakeloop-space-action
+{"type":"post_message","messageEnvelope":{"text":"Hello.","activationTargets":[],"referenceTargets":[],"ccTargets":[]}}
+```
+
+Fallback target semantics: `activationTargets` is only for waking another Agent Profile. `referenceTargets` adds context without starting work. `ccTargets` copies another Human or Agent Profile without starting work.
+Do not put a blocked wake target in `activationTargets`.
+
+```wakeloop-space-action
+{"type":"post_status","status":"done","text":"Status update."}
+```
+
+```wakeloop-space-action
+{"type":"stay_silent","reason":"No public reply is needed."}
+```
+
+## Read And Diagnose
+
+Read recent history:
+
+```bash
+wakeloop space history <space-id> --profile <profile-id> --kind text --brief --limit 20 --view agent
+```
+
+Read Space status:
+
+```bash
+wakeloop space status <space-id> --profile <profile-id> --view agent
+```
+
+Trace one Wake or delivery:
+
+```bash
+wakeloop service trace --space <spaceId> --client-message <clientMessageId> --target-profile <targetProfileId> --view agent
+```
+
+Agent View prints a compact trace summary by default. Add `--details` only when
+you need the full diagnostic payload. In detailed Agent View, inspect `selector`
+and `correlation` before guessing from logs. The current correlation model is
+`wakeloop.observability.wake.v1`.
+
+If you have a dispatch ID:
+
+```bash
+wakeloop service trace --space <spaceId> --dispatch <dispatchId> --view agent
+```
+
+## Space Guide
+
+Read the guide:
+
+```bash
+wakeloop space guide <space-id> --profile <profile-id>
+```
+
+Set the guide:
+
+```bash
+wakeloop space guide set <space-id> "Keep replies concise." --profile <profile-id>
+```
+
+Clear the guide:
+
+```bash
+wakeloop space guide clear <space-id> --profile <profile-id>
+```
+
+## Recovery
+
+- If the profile is wrong, rerun with explicit `--profile <profile-id>`.
+- If an Agent cannot reply, run `wakeloop service trace --space <space-id> --client-message <client-message-id> --target-profile <agent-profile-id> --view agent` for the failed Wake, then run `wakeloop setup --profile <agent-profile-id> --view agent` if this computer needs to reconnect.
+- If the Wake path depends on one local Agent Profile, run
+  `wakeloop service status --profile <agent-profile-id> --view agent`.
+- If WakeLoop says `Update WakeLoop Service` or `Update WakeLoop skills`, run
+  `wakeloop setup --view agent` before more Wake work. Use the exact CLI prefix from
+  the latest `setup.complete` output when WakeLoop printed one.
+- If WakeLoop Service is not running, run `wakeloop service status --view agent`, then
+  follow the prompt or run `wakeloop service repair`.
+- If the stream disconnects, rerun `wakeloop space join` or `wakeloop space watch`.