@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.
- package/DISCLOSURE +174 -0
- package/README.md +87 -12
- package/dist/cli.js +83814 -40252
- package/dist/vault-client.js +876 -0
- package/dist/vault-db.js +858 -0
- package/embedder/app.py +331 -0
- package/embedder/clip_tokenizer.py +137 -0
- package/embedder/convert_clip.py +119 -0
- package/embedder/convert_onnx.py +129 -0
- package/embedder/convert_text.py +148 -0
- package/embedder/onnx_backend.py +48 -0
- package/embedder/overrides-onnx.txt +3 -0
- package/embedder/requirements-onnx.txt +22 -0
- package/embedder/requirements.txt +20 -0
- package/embedder/serve.py +241 -0
- package/embedder/text_tokenizer.py +34 -0
- package/native/simhid.m +7 -0
- package/native/simstream.m +7 -0
- package/package.json +28 -14
- package/plugin/factiii/bin/factiii-board-mcp +206 -0
- package/plugin/factiii/bin/factiii-secrets +182 -18
- package/plugin/factiii/bin/report-state.sh +19 -1
- package/plugin/factiii/bin/session-context.sh +76 -0
- package/plugin/factiii/hooks/hooks.json +22 -0
- package/plugin/factiii/skills/board-sessions/SKILL.md +74 -0
- package/plugin/factiii/skills/factiii-secrets/SKILL.md +21 -3
- package/plugin/factiii/skills/runner-onboarding/SKILL.md +67 -0
- package/plugin/factiii/skills/scratchpad/SKILL.md +1 -0
- package/plugin/factiii/skills/share-a-port/SKILL.md +11 -6
- package/index/image-package.json +0 -8
- package/index/index.js +0 -105341
- package/native/screenhost.m +0 -500
- package/plugin/factiii/skills/factiii-workspace/SKILL.md +0 -69
- package/vendor/frpc-darwin-amd64 +0 -0
- package/vendor/frpc-darwin-arm64 +0 -0
- package/vendor/frpc-linux-amd64 +0 -0
- 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
|
|
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
|
|
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
|
|
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
|
-
- `
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
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
|
|