@factiii/runner 0.24.0 → 0.43.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/DISCLOSURE +174 -0
  2. package/README.md +87 -12
  3. package/dist/cli.js +83814 -40252
  4. package/dist/vault-client.js +876 -0
  5. package/dist/vault-db.js +858 -0
  6. package/embedder/app.py +331 -0
  7. package/embedder/clip_tokenizer.py +137 -0
  8. package/embedder/convert_clip.py +119 -0
  9. package/embedder/convert_onnx.py +129 -0
  10. package/embedder/convert_text.py +148 -0
  11. package/embedder/onnx_backend.py +48 -0
  12. package/embedder/overrides-onnx.txt +3 -0
  13. package/embedder/requirements-onnx.txt +22 -0
  14. package/embedder/requirements.txt +20 -0
  15. package/embedder/serve.py +241 -0
  16. package/embedder/text_tokenizer.py +34 -0
  17. package/native/simhid.m +7 -0
  18. package/native/simstream.m +7 -0
  19. package/package.json +28 -14
  20. package/plugin/factiii/bin/factiii-board-mcp +206 -0
  21. package/plugin/factiii/bin/factiii-secrets +182 -18
  22. package/plugin/factiii/bin/report-state.sh +19 -1
  23. package/plugin/factiii/bin/session-context.sh +76 -0
  24. package/plugin/factiii/hooks/hooks.json +22 -0
  25. package/plugin/factiii/skills/board-sessions/SKILL.md +74 -0
  26. package/plugin/factiii/skills/factiii-secrets/SKILL.md +21 -3
  27. package/plugin/factiii/skills/runner-onboarding/SKILL.md +67 -0
  28. package/plugin/factiii/skills/scratchpad/SKILL.md +1 -0
  29. package/plugin/factiii/skills/share-a-port/SKILL.md +11 -6
  30. package/index/image-package.json +0 -8
  31. package/index/index.js +0 -105341
  32. package/native/screenhost.m +0 -500
  33. package/plugin/factiii/skills/factiii-workspace/SKILL.md +0 -69
  34. package/vendor/frpc-darwin-amd64 +0 -0
  35. package/vendor/frpc-darwin-arm64 +0 -0
  36. package/vendor/frpc-linux-amd64 +0 -0
  37. package/vendor/frpc-linux-arm64 +0 -0
@@ -1,5 +1,16 @@
1
1
  {
2
2
  "hooks": {
3
+ "SessionStart": [
4
+ {
5
+ "hooks": [
6
+ {
7
+ "type": "command",
8
+ "command": "\"${CLAUDE_PLUGIN_ROOT}/bin/session-context.sh\"",
9
+ "timeout": 5
10
+ }
11
+ ]
12
+ }
13
+ ],
3
14
  "UserPromptSubmit": [
4
15
  {
5
16
  "hooks": [
@@ -11,6 +22,17 @@
11
22
  ]
12
23
  }
13
24
  ],
25
+ "PreToolUse": [
26
+ {
27
+ "hooks": [
28
+ {
29
+ "type": "command",
30
+ "command": "\"${CLAUDE_PLUGIN_ROOT}/bin/report-state.sh\" working",
31
+ "timeout": 5
32
+ }
33
+ ]
34
+ }
35
+ ],
14
36
  "Stop": [
15
37
  {
16
38
  "hooks": [
@@ -0,0 +1,74 @@
1
+ ---
2
+ name: board-sessions
3
+ description: See, start, message, read and end the other agent sessions (Chat and Code) on your boards, with the factiii-board MCP's session tools. TRIGGER when the user asks to spin up another agent or session, hand a task to a new agent, check on or talk to another session, see what other agents are doing, or end/clean up sessions.
4
+ license: ISC
5
+ ---
6
+
7
+ # board-sessions
8
+
9
+ The `factiii-board` MCP server has tools the runner answers itself, for the
10
+ sessions it holds. Your own session:
11
+
12
+ - `session_card`, `link_card { postId }`, `unlink_card`: the card this
13
+ session works on.
14
+ - `set_work_path { path }`: point this session's IDE at another folder.
15
+
16
+ Every other session on the boards you can use, on this runner and on the
17
+ other runners (and the desktop app on your computer) you can reach, through
18
+ Factiii's server:
19
+
20
+ - `list_runners`: this runner first, then each other one online, with its
21
+ `id` (what `runner` takes: `r12`, `desktop:5`), the boards you reach there,
22
+ what it offers (`os`, `tart` VMs, the iOS `simulator`, a `gpu`), and
23
+ whether its owner lets sessions be started there from other runners.
24
+ - `list_sessions { board? }`: board, runner (where it runs) and runnerName,
25
+ id, title, state (starting, working, idle, needs you, error), mode (Chat or
26
+ Code), linked card, and here also worktree and which session started it.
27
+ - `start_session { mode, message, board?, title?, cardId?, baseBranch?,
28
+ runner? }`: `code` gets its own worktree and branch named after `title`
29
+ (required); `chat` runs in the board's workspace. `message` is its task; it
30
+ goes in once the workspace is ready. Returns the new id. With `runner`, it
31
+ starts on that runner, if its owner allowed starts from other runners, and
32
+ runs with that runner's own permissions.
33
+ - `message_session { session, text, board?, runner? }`: lands in its inbox
34
+ and goes in once any turn in progress ends; it never interrupts one. A
35
+ session on an offline runner gets it when that runner is back (held 7
36
+ days, then expired). Says whether it was delivered or is waiting.
37
+ - `read_session { session, board?, runner?, limit?, wait? }`: its recent
38
+ transcript and, for Code, branch, dirty files, ahead/behind and unpushed
39
+ commits. `wait` (seconds, up to 600) waits for its turn to end and adds its
40
+ final answer as `summary`.
41
+ - `end_session { session, board?, discard?, deleteBranch? }`: stops a session
42
+ on this runner and removes its worktree. The branch is kept unless
43
+ `deleteBranch: true`.
44
+
45
+ ## Rules the runner enforces
46
+
47
+ - You can do only what the person your session acts for could do by hand on
48
+ that board. A session you start acts for the same person.
49
+ - At most 5 sessions started this way run at once on a board. End one you no
50
+ longer need before starting another.
51
+ - `end_session` refuses a worktree with uncommitted files or commits no
52
+ remote has. Ask the session to commit and push (`message_session`), check
53
+ with `read_session`, then end it. Pass `discard: true` only when the user
54
+ said the work may be lost.
55
+ - You cannot end your own session this way.
56
+ - A message is at most 16,000 characters, at most 30 a minute, and never
57
+ holds a secret (a token, a key, a password): it is refused. No secrets
58
+ cross between runners; a session reads its own runner's.
59
+ - On another runner you reach only the boards its owner gave you Shell on
60
+ (all of them on your own runners).
61
+ - Every start, message and end is in the runner's audit log under your
62
+ session's id; a message or start to another runner is in both runners'.
63
+
64
+ ## Working with them
65
+
66
+ - Ask before starting a session the user did not ask for, and say what it
67
+ will do. Link it to the card it works on (`cardId`).
68
+ - A new session needs a while to start: poll `list_sessions` or
69
+ `read_session` instead of messaging it at once.
70
+ - Do not wait in a tight loop. Check back after a minute or two, or use
71
+ `read_session { wait: 600 }` to wait for its answer in one call.
72
+ - To hand work to another machine ("open a Tart VM, run X, report back"):
73
+ `list_runners`, `start_session { runner, board, mode: "chat", message }`,
74
+ then `read_session { runner, board, session, wait: 600 }` for the result.
@@ -1,6 +1,7 @@
1
1
  ---
2
2
  name: factiii-secrets
3
3
  description: Run a command that needs this workspace's stored secrets, with factiii-secrets. TRIGGER when a command needs an API token, deploy credential, database URL or any other secret value, when writing or revising a deploy skill, or whenever an environment variable a step needs appears to be missing.
4
+ license: ISC
4
5
  ---
5
6
 
6
7
  # factiii-secrets
@@ -54,7 +55,7 @@ a server's whole `.env`. Ask for those with `--file`. The runner writes each
54
55
  one to a private temp file (mode 0600) and puts its PATH in `$NAME`:
55
56
 
56
57
  ```bash
57
- factiii-secrets run --file STAGING_DEPLOY_KEY -- ssh -i "$STAGING_DEPLOY_KEY" deploy@host ./release.sh
58
+ factiii-secrets run --file DEPLOY_SSH_KEY -- ssh -i "$DEPLOY_SSH_KEY" deploy@host ./release.sh
58
59
  factiii-secrets run --key EXPO_TOKEN --file ASC_API_KEY_P8 -- ./scripts/submit-ios.sh
59
60
  ```
60
61
 
@@ -96,8 +97,7 @@ FOR:
96
97
 
97
98
  ```
98
99
  DATABASE_URL set, declared Primary Postgres URL
99
- The database migrations run against. Points at prod; staging
100
- has its own.
100
+ The database migrations run against. Points at prod.
101
101
  EXPO_TOKEN not set, declared Expo access token
102
102
  Authenticates the EAS CLI for mobile builds and submits.
103
103
  OLD_TOKEN set, undeclared
@@ -119,6 +119,24 @@ does not cover you: every `factiii-secrets run` from a terminal or a card
119
119
  session still asks a password holder, every time. Do not wait for, rely on,
120
120
  or ask anyone to open a window to avoid the prompt.
121
121
 
122
+ **A job does ride the window.** Before a free command, check
123
+ `factiii-runner job --list`: if a job does the same thing (a deploy, a GitHub
124
+ release step, a log read), call it instead. Inside an open window it runs with
125
+ no prompt, and when the runner is locked one password opens the window for the
126
+ jobs after it too. If no job fits and the step will come back (a release
127
+ step, a recurring read), say so: offer the user the choice of approving this
128
+ one command, or adding a job to the repo's job list so it never asks inside a
129
+ window again.
130
+
131
+ That prompt is the gate, so the runner tells your CLI to let the command
132
+ through without its own check: an allow rule in Claude's user settings, and
133
+ `$CODEX_HOME/rules/factiii.rules` for Codex. Both are in the runner's own
134
+ homes (`$CLAUDE_CONFIG_DIR`, `$CODEX_HOME`), not in `~/.claude` or `~/.codex`,
135
+ so they apply to runner sessions only. Keep the command plain so the rule
136
+ matches. Codex still asks about a command that has `$(...)`, a redirect or a
137
+ `$VARIABLE` in it, and anything chained before or after with `&&`, `;` or `|`
138
+ gets the CLI's normal check.
139
+
122
140
  ## Things that will waste your time
123
141
 
124
142
  - **Do not check whether these variables are set.** They are unset in your
@@ -0,0 +1,67 @@
1
+ ---
2
+ name: runner-onboarding
3
+ description: Walk the owner of a runner that Factiii Desktop just set up through the rest - a board, a repository, secrets, keeping the Mac on - and install the tools a feature needs (git, sops, Ollama, Tailscale, Xcode) only when that feature is first wanted, asking first. TRIGGER when a session's first message says the runner was just set up, when the user asks to finish setting up this runner or this Mac, or asks what to do next with a new runner.
4
+ license: ISC
5
+ ---
6
+
7
+ # runner-onboarding
8
+
9
+ Factiii Desktop has already done the minimum: this Mac is a runner, paired to
10
+ the person's account and online; the AI (you) is installed and signed in;
11
+ tmux, Valkey, age and frpc are in `$FACTIII_TOOLS_DIR`. Everything else is
12
+ optional, and you set it up by talking it through.
13
+
14
+ ## How to run it
15
+
16
+ - **One step at a time.** Say what the step is for in a line, ask, and wait.
17
+ "Skip" is always an answer; skip and move on.
18
+ - **Ask before every install**, naming what it is, its size, and whether
19
+ macOS will ask for a password. Install nothing that no step needs.
20
+ - **Never use sudo and never ask for a password yourself.** Admin steps go
21
+ through macOS's own dialog (an installer, `xcode-select --install`, System
22
+ Settings), which the person answers.
23
+ - **Never ask for a secret in the chat.** Values go into the board's store
24
+ from the app (Settings > Secrets); you use them through `factiii-secrets`.
25
+ - Install a command-line tool into `~/.local/bin` (on the runner's PATH),
26
+ never into `$FACTIII_TOOLS_DIR`, which the app replaces on every update.
27
+ - Check first (`command -v <tool>`, `factiii-runner doctor`): a step this Mac
28
+ already has is only mentioned.
29
+
30
+ ## The steps
31
+
32
+ 1. **Where things stand.** Run `factiii-runner status` and
33
+ `factiii-runner doctor`; tell the person in three lines what works and
34
+ what this walk-through can add.
35
+ 2. **A board.** This session runs on a board (the `session_card` and
36
+ `list_sessions` tools of the `factiii-board` MCP name it). Ask what they
37
+ want to work on. A project of their own gets its own board: they make it
38
+ in the app (New board), then pick this runner for it. Offer to put their
39
+ first tasks on it as cards (`create_card`).
40
+ 3. **A repository** (only if they code). Git is the first tool on demand,
41
+ below. Connecting GitHub is the runner's, once for every board: Status >
42
+ Git in the runner window. Then the board's Settings names the repository.
43
+ 4. **Secrets** (only if a project needs API keys or deploy credentials).
44
+ Explain the store in two lines: encrypted on this Mac, each use approved
45
+ by them. It needs `sops` (on demand, below; `age` is already there). They
46
+ add the values in the board's Settings > Secrets; show them how a command
47
+ uses one with the `factiii-secrets` skill.
48
+ 5. **Keeping it on.** If the runner should answer while they are away: the
49
+ optional rows of Set up this computer (in the Factiii app menu): start
50
+ after a restart, keep the Mac awake, log in automatically.
51
+ 6. **Wrap up.** List what is set, what was skipped, and how to come back to
52
+ it (ask for this walk-through again, or Status in the runner window).
53
+
54
+ ## Tools on demand
55
+
56
+ Only when the step or feature that needs it comes up, and only after a yes.
57
+
58
+ | Tool | Needed for | How (macOS) |
59
+ | --- | --- | --- |
60
+ | git | a repository, Code sessions | `xcode-select --install`: macOS's own dialog installs the Command Line Tools (about 1 GB, a few minutes, no password). Check with `xcode-select -p`. `/usr/bin/git` before that only opens the same dialog. |
61
+ | sops | the secrets store | `brew install sops` if `brew` is there. Else the official release: `sops-v<version>.darwin.<arm64\|amd64>` from github.com/getsops/sops/releases, checked against that release's `sops-v<version>.checksums.txt` with `shasum -a 256` before it is moved to `~/.local/bin/sops` and made executable. A mismatch: stop and say so. |
62
+ | Ollama | Local AI (private models on this Mac) | Status > Features > Local AI adds it through Homebrew. Without Homebrew: the official app, ollama.com/download (Ollama.dmg, drag to Applications, open it once). Then the model step in Status picks a model that fits this Mac. |
63
+ | Tailscale | reaching this Mac when Factiii is down, or from their other machines | The person installs it: the Mac App Store or tailscale.com/download, then signs in with their own account. You only check `tailscale status` afterwards. |
64
+ | Xcode | iOS builds and the iOS simulator | The person installs it from the Mac App Store (many GB, a long download), then opens Xcode once to accept its license and add its components (macOS asks for their password). You check `xcodebuild -version` afterwards. |
65
+
66
+ Anything else a feature needs: `factiii-runner doctor` names it and the
67
+ command; say what it is for and ask before running it.
@@ -1,6 +1,7 @@
1
1
  ---
2
2
  name: scratchpad
3
3
  description: Show the user something, or hand them a file, through the board's Scratchpad panel - by writing to $SCRATCHPAD. Anything you put there renders beside the terminal (image, screenshot, chart, video, audio, page, link, text) and can be saved to their machine or phone. TRIGGER when the user asks to see, show, preview, display or look at something; when you produce an image/diagram/chart/screenshot/recording; when you have a URL worth opening; when an answer is easier to look at than to read in a terminal; and whenever you need to GIVE the user a file - an export, a report, a bundle, a CSV, a log, a dump, anything they asked you to generate, save, download or send them. Writing it to $SCRATCHPAD is how a file gets off the runner and to the user.
4
+ license: ISC
4
5
  ---
5
6
 
6
7
  # scratchpad
@@ -1,6 +1,7 @@
1
1
  ---
2
2
  name: share-a-port
3
3
  description: Give a port running in this workspace a public HTTPS URL, with factiii-expose. TRIGGER when the user asks to share, expose, preview or publish a local server, wants a link to something running on localhost, or needs an external service to reach a local port.
4
+ license: ISC
4
5
  ---
5
6
 
6
7
  # share-a-port
@@ -15,7 +16,9 @@ factiii-expose <port> <name> # e.g. factiii-expose 3000 app
15
16
  ```
16
17
 
17
18
  It prints the public URL and returns straight away - the tunnel runs in the
18
- background and lives until the session ends or you stop it.
19
+ background and keeps running after the session ends, renewing its own
20
+ credential, until you stop it with `factiii-unexpose <name>` or the machine
21
+ restarts.
19
22
 
20
23
  - `<name>` may hold letters, numbers and dashes only.
21
24
  - Re-running it with the same name replaces that tunnel rather than opening a
@@ -42,11 +45,13 @@ Two more `.env` values matter once the app has logins, and both fail silently:
42
45
  - `COOKIE_DOMAIN` — the two tunnels are different hostnames under one parent, so
43
46
  a host-only cookie set on the web host is never sent to the api host. Every
44
47
  authenticated call 401s while the UI looks signed in.
45
- - `NEXT_PUBLIC_COOKIE_PREFIX` — must differ from production's. A preview under
46
- `*.dev.factiii.com` also receives cookies scoped to `.factiii.com`, so anyone
47
- logged into the real site sends a same-named cookie that shadows the
48
- preview's, and signing in simply does not stick. `.env.example` already ships
49
- a distinct value; keep it distinct.
48
+ - `COOKIE_DOMAIN=.factiii.org` — previews are `https://<name>.factiii.org`
49
+ (2026-11-11). It is not under factiii.com, so a preview never receives a
50
+ visitor's real Factiii cookies. A link printed by an older runner,
51
+ `*.dev.factiii.com`, still works until every runner has moved, but there it
52
+ receives `.factiii.com` cookies again.
53
+ - `NEXT_PUBLIC_COOKIE_PREFIX` — keep it different from production's.
54
+ `.env.example` already ships a distinct value.
50
55
 
51
56
  ## Stop sharing
52
57
 
@@ -1,8 +0,0 @@
1
- {
2
- "name": "factiii-index-image",
3
- "private": true,
4
- "dependencies": {
5
- "better-sqlite3": "^12.11.1",
6
- "sqlite-vec": "^0.1.6"
7
- }
8
- }