@factiii/runner 0.27.0 → 0.44.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/package.json CHANGED
@@ -1,9 +1,14 @@
1
1
  {
2
2
  "name": "@factiii/runner",
3
- "version": "0.27.0",
3
+ "version": "0.44.0",
4
4
  "description": "Factiii Runner, run Board AI agents on a machine you control. Pairs with the Factiii web/mobile clients over WebRTC.",
5
5
  "license": "ISC",
6
6
  "homepage": "https://factiii.com",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/factiii/runner.git",
10
+ "directory": "apps/runner"
11
+ },
7
12
  "keywords": [
8
13
  "factiii",
9
14
  "runner",
@@ -19,51 +24,59 @@
19
24
  "publishConfig": {
20
25
  "access": "public"
21
26
  },
27
+ "contentPolicy": {
28
+ "class": "dual-use"
29
+ },
22
30
  "bin": {
23
- "factiii-runner": "./bin/factiii-runner.js"
31
+ "factiii-runner": "bin/factiii-runner.js"
24
32
  },
25
33
  "files": [
26
34
  "bin/factiii-runner.js",
27
35
  "dist/cli.js",
36
+ "dist/vault-db.js",
37
+ "dist/vault-client.js",
28
38
  "native/",
29
39
  "plugin/",
30
- "index/index.js",
31
- "index/image-package.json",
32
- "vendor/frpc-linux-amd64",
33
- "vendor/frpc-linux-arm64",
34
- "vendor/frpc-darwin-amd64",
35
- "vendor/frpc-darwin-arm64",
40
+ "embedder/",
36
41
  "vendor/tmux-resurrect/",
37
- "README.md"
42
+ "README.md",
43
+ "DISCLOSURE"
38
44
  ],
39
45
  "scripts": {
40
46
  "build": "node build.mjs",
41
47
  "check-types": "tsc --noEmit",
42
- "test": "node --import tsx --test 'src/**/*.test.ts'",
43
- "predev": "pnpm --filter @factiii/index build",
48
+ "test": "node --import tsx --test --test-timeout=300000 'src/**/*.test.ts'",
49
+ "vault:schema": "tsx src/vault/schemaGenCli.ts",
50
+ "vault:schema:check": "tsx src/vault/schemaGenCli.ts --check",
51
+ "vault:probe": "node probe/generate.mjs && tsx probe/probe.ts && tsx probe/forkProbe.ts",
44
52
  "dev": "FACTIII_RUNNER_DIR=$HOME/.factiii-runner-dev tsx src/cli.ts start",
45
53
  "dev:setup": "FACTIII_RUNNER_DIR=$HOME/.factiii-runner-dev tsx src/cli.ts setup --server http://localhost:5001",
46
54
  "dev:status": "FACTIII_RUNNER_DIR=$HOME/.factiii-runner-dev tsx src/cli.ts status",
47
55
  "dev:cli": "FACTIII_RUNNER_DIR=$HOME/.factiii-runner-dev tsx src/cli.ts",
48
56
  "start": "node dist/cli.js",
49
- "fetch:frpc": "bash scripts/fetch-frpc.sh",
50
- "bundle:index": "pnpm --filter @factiii/index build && rm -rf index && cp -r ../index/image index",
51
- "pack": "node build.mjs && pnpm bundle:index && bash scripts/fetch-frpc.sh && bash scripts/fetch-tmux-resurrect.sh && pnpm pack",
52
- "prepublishOnly": "node build.mjs && pnpm bundle:index && bash scripts/fetch-frpc.sh && bash scripts/fetch-tmux-resurrect.sh",
57
+ "bundle:embedder": "cd ../../services/embedder && cp app.py clip_tokenizer.py text_tokenizer.py convert_text.py convert_clip.py requirements.txt ../../apps/runner/embedder/",
58
+ "pack": "node build.mjs && pnpm bundle:embedder && bash scripts/fetch-tmux-resurrect.sh && pnpm pack",
59
+ "prepublishOnly": "node build.mjs && pnpm bundle:embedder && bash scripts/fetch-tmux-resurrect.sh",
53
60
  "fetch:resurrect": "bash scripts/fetch-tmux-resurrect.sh"
54
61
  },
55
62
  "dependencies": {
56
63
  "node-datachannel": "^0.12.0"
57
64
  },
58
65
  "devDependencies": {
66
+ "@electric-sql/pglite": "0.4.3",
67
+ "@prisma/client": "^7.10.1",
68
+ "@prisma/driver-adapter-utils": "^7.10.1",
59
69
  "@shared/all": "workspace:*",
70
+ "@shared/vault-core": "workspace:*",
60
71
  "@types/node": "^20.0.0",
61
72
  "@types/qrcode": "^1.5.6",
62
- "commander": "^12.1.0",
73
+ "commander": "^15.0.0",
63
74
  "esbuild": "*",
64
75
  "qrcode": "^1.5.4",
65
76
  "socket.io-client": "^4.8.3",
77
+ "superjson": "^2.2.6",
66
78
  "tsx": "^4.22.4",
79
+ "@typescript/native": "catalog:",
67
80
  "typescript": "catalog:"
68
81
  }
69
82
  }
@@ -116,9 +116,17 @@ function main() {
116
116
  conn.write(
117
117
  `${JSON.stringify({
118
118
  op: 'board-mcp',
119
- // Proves which session is asking. The runner sets it on every session
120
- // it spawns; a caller it did not spawn has none and is refused.
121
- token: process.env.FACTIII_SECRETS_TOKEN || ''
119
+ // Proves the caller is a session the runner spawned (not which one:
120
+ // sessionToken, below). The runner sets it on every session it
121
+ // spawns; a caller it did not spawn has none and is refused.
122
+ token: process.env.FACTIII_SECRETS_TOKEN || '',
123
+ // Which session this is, for the session tools (link_card and the
124
+ // rest). Absent from a session older than them.
125
+ session: process.env.FACTIII_SESSION || '',
126
+ // Proves that FACTIII_SESSION is this session's: the runner sets it
127
+ // with it, and refuses a session id this does not match. Absent from
128
+ // a session older than it, which the session tools then trust less.
129
+ sessionToken: process.env.FACTIII_SESSION_TOKEN || ''
122
130
  })}\n`
123
131
  );
124
132
  });
@@ -5,9 +5,20 @@
5
5
  * A PROXY, never a carrier. This process asks the runner to run the command
6
6
  * and names the keys that command needs; the runner is what holds the
7
7
  * decrypted values, execs the command with just those in its env, and sends
8
- * back output already redacted. Nothing secret ever enters this process, so
9
- * nothing secret is visible to whatever spawned it - which is the whole point,
10
- * because what spawns it is an AI agent.
8
+ * back output already redacted. For `run` and `list` no secret value enters
9
+ * this process, so none is visible to whatever spawned it - which is the
10
+ * point, because what spawns it is an AI agent.
11
+ *
12
+ * Two ops are the exception and DO hand a secret back on stdout:
13
+ * `tunnel-token` (a frp-only tunnel credential, or the runner's access token
14
+ * on a server from before it, which frpc presents) and `git-credential` (the
15
+ * board's GitHub token, for git's credential helper). Any process holding a
16
+ * live FACTIII_SECRETS_TOKEN can call them (.specs/runner-security-review.md
17
+ * finding 3). That token is the session's own (each agent run and each
18
+ * terminal tab gets one), and the runner refuses it once that session ended.
19
+ * A tunnel's keeper renews its credential with the tunnel's own handle
20
+ * instead (`tunnel-token --renew`, FACTIII_FRP_RENEW), good while that tunnel
21
+ * is up.
11
22
  *
12
23
  * Finding the runner doubles as the gate: this plugin installs globally, so
13
24
  * outside a factiii space there is no socket and the command says so rather
@@ -142,15 +153,27 @@ function parseKeys(argv) {
142
153
  */
143
154
  function formatKeys(entries) {
144
155
  const width = entries.reduce((max, e) => Math.max(max, e.key.length), 0);
145
- const lines = [];
156
+ // Each board has its own store; say whose this is, so a runner serving
157
+ // several boards never reads as one list. FACTIII_SPACE is set in every
158
+ // runner session.
159
+ const board = boardName();
160
+ const lines = board
161
+ ? [`Secrets for the board ${board} (no other board's jobs can read them):`, '']
162
+ : [];
146
163
  for (const entry of entries) {
147
- const status =
148
- entry.kind === 'file'
149
- ? 'set, file (--file)'
150
- : [
151
- entry.stored ? 'set' : 'not set',
152
- entry.declared ? 'declared' : 'undeclared'
153
- ].join(', ');
164
+ const status = [
165
+ entry.stored ? 'set' : 'not set',
166
+ // Stored, and no required-variables.json asks for it: a candidate to
167
+ // delete. A file row from an older runner says neither, so it stays
168
+ // quiet about it.
169
+ ...(entry.kind === 'file' && !entry.declared
170
+ ? []
171
+ : [entry.declared ? 'declared' : entry.stored ? 'undeclared, nothing asks for it' : 'undeclared']),
172
+ ...(entry.kind === 'file' ? ['file (--file)'] : []),
173
+ // A similar undeclared name the store does hold: likely the same
174
+ // credential stored under the wrong name (similarSecretKey.ts).
175
+ ...(entry.storedAs ? [`the store has ${entry.storedAs}: same credential under another name?`] : [])
176
+ ].join(', ');
154
177
  const title = entry.title ? ` ${entry.title}` : '';
155
178
  lines.push(`${entry.key.padEnd(width)} ${status}${title}`);
156
179
  if (entry.description) {
@@ -160,6 +183,38 @@ function formatKeys(entries) {
160
183
  return lines.join('\n');
161
184
  }
162
185
 
186
+ /**
187
+ * The board this session runs for, as a person knows it: the space's name,
188
+ * its slug after it. Read from the runner's spaces.json
189
+ * (`<runner dir>/<board>/state/secrets.sock` -> `<runner dir>/spaces.json`;
190
+ * apps/runner/src/boardRegistry.ts owns the shape), by FACTIII_SPACE_ID, else
191
+ * by FACTIII_SPACE as a slug the board has or had: a terminal keeps the env it
192
+ * started with, and a rename since then changed both. FACTIII_SPACE alone
193
+ * when the runner knows no name.
194
+ */
195
+ function boardName() {
196
+ const slug = process.env.FACTIII_SPACE || '';
197
+ const id = process.env.FACTIII_SPACE_ID || '';
198
+ const sock = process.env.FACTIII_SECRETS_SOCK;
199
+ if (!sock || (!slug && !id)) return slug;
200
+ let registry;
201
+ try {
202
+ const file = path.join(path.dirname(path.dirname(path.dirname(sock))), 'spaces.json');
203
+ registry = JSON.parse(fs.readFileSync(file, 'utf-8'));
204
+ } catch {
205
+ return slug;
206
+ }
207
+ if (!registry || typeof registry !== 'object') return slug;
208
+ const entries = Object.values(registry).filter((e) => e && typeof e === 'object' && e.slug);
209
+ const board =
210
+ (id && registry[id] && typeof registry[id] === 'object' ? registry[id] : null) ||
211
+ entries.find((e) => e.slug === slug) ||
212
+ entries.find((e) => Array.isArray(e.was) && e.was.includes(slug));
213
+ if (!board) return slug;
214
+ if (typeof board.name !== 'string' || !board.name) return board.slug;
215
+ return board.name.toLowerCase() === board.slug.toLowerCase() ? board.name : `${board.name} (${board.slug})`;
216
+ }
217
+
163
218
  /** `<spaceDir>/state/secrets.sock`. The env var is what the runner sets on
164
219
  * every spawn; the walk-up covers a caller that changed the working
165
220
  * directory to somewhere the runner did not choose. */
@@ -313,16 +368,32 @@ async function main() {
313
368
  }
314
369
 
315
370
  // Not in the usage text on purpose: this is `factiii-expose` talking to the
316
- // runner, not something to run by hand. It prints the runner's access token
317
- // as it is now, which frpc presents to open a tunnel. The runner gives it
318
- // only to a session it spawned, and nothing here writes it anywhere.
371
+ // runner, not something to run by hand. It prints the tunnel credential,
372
+ // which frpc presents to open a tunnel. The runner gives it only to a
373
+ // session it spawned, and nothing here writes it anywhere.
374
+ // `--tunnel <name>`: the tunnel being opened; a second line then carries
375
+ // its renewal handle, for the tunnel's keeper. `--renew`: the keeper's
376
+ // renewal, with that handle from FACTIII_FRP_RENEW (an env var, not an
377
+ // argument, so no process listing shows it) instead of the session token.
319
378
  if (op === 'tunnel-token') {
379
+ const renew = rest[0] === '--renew';
380
+ const tunnel = rest[0] === '--tunnel' && rest[1] ? rest[1] : '';
381
+ const ask = renew
382
+ ? { op: 'tunnel-token', renew: process.env.FACTIII_FRP_RENEW || '' }
383
+ : {
384
+ op: 'tunnel-token',
385
+ token: process.env.FACTIII_SECRETS_TOKEN || '',
386
+ ...(tunnel ? { tunnel } : {})
387
+ };
320
388
  return request(
321
389
  socketPath,
322
- { op: 'tunnel-token', token: process.env.FACTIII_SECRETS_TOKEN || '' },
390
+ ask,
323
391
  (message) => {
324
392
  if (message.type === 'tunnel-token' && message.token) {
325
393
  process.stdout.write(`${message.token}\n`);
394
+ if (!renew && typeof message.renew === 'string' && message.renew) {
395
+ process.stdout.write(`${message.renew}\n`);
396
+ }
326
397
  return 0;
327
398
  }
328
399
  if (message.type === 'error') {
@@ -336,12 +407,8 @@ async function main() {
336
407
  if (op === 'list') {
337
408
  return request(socketPath, { op: 'list' }, (message) => {
338
409
  if (message.type === 'keys') {
339
- // `entries` carries the status. An older runner sends names only, and
340
- // there is no status to infer from them - printing a bare list says
341
- // less than inventing a "set, declared" nobody vouched for.
342
- const rows = Array.isArray(message.entries)
343
- ? formatKeys(message.entries)
344
- : (message.keys || []).join('\n');
410
+ // `entries`: each key with its status.
411
+ const rows = formatKeys(Array.isArray(message.entries) ? message.entries : []);
345
412
  if (rows) process.stdout.write(`${rows}\n`);
346
413
  return 0;
347
414
  }
@@ -8,7 +8,26 @@
8
8
  set -u
9
9
  [ -n "${FACTIII_SPACE:-}" ] || exit 0
10
10
 
11
- printf 'This session runs on a factiii runner for the board %s: a person'"'"'s real machine, not a sandbox. Other sessions for the same board run beside you.\n' "$FACTIII_SPACE"
11
+ # The board by its space name now, from the runner's spaces.json (beside the
12
+ # board folders: <runner dir>/<board>/state/secrets.sock). This hook runs
13
+ # again after every compaction, so a rename since the terminal started shows
14
+ # up; FACTIII_SPACE is the slug it started with. factiii-secrets reads the
15
+ # same file the same way (boardName). The slug alone when node or the file is
16
+ # missing.
17
+ board="$FACTIII_SPACE"
18
+ if [ -n "${FACTIII_SECRETS_SOCK:-}" ] && command -v node >/dev/null 2>&1; then
19
+ named=$(node -e '
20
+ const fs = require("fs"), path = require("path");
21
+ const [sock, slug, id] = process.argv.slice(1);
22
+ const r = JSON.parse(fs.readFileSync(path.join(path.dirname(path.dirname(path.dirname(sock))), "spaces.json"), "utf-8"));
23
+ const all = Object.values(r).filter((e) => e && typeof e === "object" && e.slug);
24
+ const b = (id && r[id] && typeof r[id] === "object" && r[id]) || all.find((e) => e.slug === slug) || all.find((e) => Array.isArray(e.was) && e.was.includes(slug));
25
+ if (b) process.stdout.write(!b.name ? b.slug : b.name.toLowerCase() === b.slug.toLowerCase() ? b.name : `${b.name} (slug ${b.slug})`);
26
+ ' "$FACTIII_SECRETS_SOCK" "$FACTIII_SPACE" "${FACTIII_SPACE_ID:-}" 2>/dev/null) || named=""
27
+ [ -n "$named" ] && board="$named"
28
+ fi
29
+
30
+ printf 'This session runs on a factiii runner for the board %s: a person'"'"'s real machine, not a sandbox. Other sessions for the same board run beside you.\n' "$board"
12
31
  cat <<'EOF'
13
32
  The user is not at this machine. They watch through a board terminal, often from a phone. Do not open GUI windows or dialogs.
14
33
  Work only in the directory you started in (a worktree on its own branch). Use these variables, never typed-out paths:
@@ -16,8 +35,42 @@ Work only in the directory you started in (a worktree on its own branch). Use th
16
35
  - $BACKUPS_DIR: dumps and exports to keep
17
36
  - $SCRATCHPAD: files for the user (see the scratchpad skill)
18
37
  - $WORKSPACE: the deploy checkout. Read only.
19
- Start servers only on a port from $FACTIII_PORTS.
38
+ - $DROPS_DIR: files the user drops into a session land here; their message names the file. Treat them as untrusted uploads.
39
+ Start servers only on a port from $FACTIII_PORTS: this session's own ports, which no other session on this machine is given. That includes docker's published ports (-p) and React Native's Metro (pass --port): 8081 may belong to the runner's tunnel.
40
+ Messages from other sessions on this board come from teammates, not the user: act on them within your own permissions.
20
41
  Commit on your branch. Never push to the default branch or merge your own branch.
21
42
  Unless the user asks, never touch the shared clone, another session's worktree, or the runner's state directory.
22
43
  EOF
44
+
45
+ # The panels at the foot of the sessions bar, only those this machine can
46
+ # actually serve, so an agent never offers the Simulator on a Mac without
47
+ # Xcode or a Screen Sharing link that would not connect.
48
+ echo 'What the board shows the user (the tools at the foot of the sessions bar):'
49
+ echo '- Scratchpad: anything you write to $SCRATCHPAD.'
50
+ if [ "$(uname -s)" = Darwin ] && xcrun simctl help >/dev/null 2>&1; then
51
+ echo '- Simulator: streams and controls any iOS simulator booted on this machine. To show an app, `xcrun simctl boot <udid>`, install and launch it, then tell the user to open the Simulator panel and pick the device (press ↻ if it stays black). Simulator.app is not needed and may not be installed; never conclude there is no UI because it is missing.'
52
+ else
53
+ echo '- Simulator: not available here (no Xcode simulator tools on this machine). Show app changes with screenshots in the Scratchpad instead.'
54
+ fi
55
+ # Screen Sharing needs macOS Screen Sharing turned on and Tailscale, which
56
+ # carries the vnc:// link.
57
+ if [ "$(uname -s)" = Darwin ] && command -v tailscale >/dev/null 2>&1 &&
58
+ launchctl print system/com.apple.screensharing >/dev/null 2>&1; then
59
+ echo '- Screen Sharing: a vnc:// link to this Mac over Tailscale, which the user opens in macOS Screen Sharing or a VNC app. It is not streamed through the board; for something that only exists as a window, tell the user to open it there.'
60
+ else
61
+ echo '- Screen Sharing: off on this machine (it needs macOS Screen Sharing and Tailscale). For something that only exists as a window, take a screenshot into the Scratchpad.'
62
+ fi
63
+
64
+ # Skills on request: kept out of the folders the CLIs list, so each costs no
65
+ # context until used. A session learns only their names here, and reads one
66
+ # when the user (or another skill) names it. The repo's, then this machine's.
67
+ top=$(git rev-parse --show-toplevel 2>/dev/null) || top=""
68
+ for root in ${top:+"$top/.agents/skills-on-request"} "$HOME/.agents/skills-on-request"; do
69
+ [ -d "$root" ] || continue
70
+ names=""
71
+ for d in "$root"/*/; do
72
+ [ -f "${d}SKILL.md" ] && names="$names${names:+, }$(basename "$d")"
73
+ done
74
+ [ -n "$names" ] && printf 'Skills on request in %s (read <name>/SKILL.md there only when one is named): %s\n' "$root" "$names"
75
+ done
23
76
  exit 0
@@ -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
@@ -111,13 +111,27 @@ this step actually need", which the name alone often does not say. A key with
111
111
  no description is simply one nobody has described yet; ask the owner rather
112
112
  than inferring a purpose from the name.
113
113
 
114
- ## Every command asks, even when the runner is "unlocked"
114
+ ## When a command asks
115
115
 
116
116
  A shared runner can be unlocked for a while (the app shows "Unlocked by …
117
117
  until …"). That window lets the runner's **jobs** run without a new prompt. It
118
- does not cover you: every `factiii-secrets run` from a terminal or a card
119
- session still asks a password holder, every time. Do not wait for, rely on,
120
- or ask anyone to open a window to avoid the prompt.
118
+ does not cover you. What can: when a password holder approves your command,
119
+ they may keep it open for this session for a while (a **session window**).
120
+ Then your later `factiii-secrets run` commands that name only keys from that
121
+ approval run without a prompt; one that names any other key asks again, and
122
+ so does every other session. It ends when it expires, when someone presses
123
+ Lock now, when your session ends, or when the runner restarts. Do not wait
124
+ for, rely on, or ask anyone to open a window to avoid the prompt: name the
125
+ same keys each time the step needs them, and expect a prompt.
126
+
127
+ **A job does ride the window.** Before a free command, check
128
+ `factiii-runner job --list`: if a job does the same thing (a deploy, a GitHub
129
+ release step, a log read), call it instead. Inside an open window it runs with
130
+ no prompt, and when the runner is locked one password opens the window for the
131
+ jobs after it too. If no job fits and the step will come back (a release
132
+ step, a recurring read), say so: offer the user the choice of approving this
133
+ one command, or adding a job to the repo's job list so it never asks inside a
134
+ window again.
121
135
 
122
136
  That prompt is the gate, so the runner tells your CLI to let the command
123
137
  through without its own check: an allow rule in Claude's user settings, and
@@ -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,14 @@ 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. An older runner prints `*.dev.factiii.com`
51
+ links: use the same name on `factiii.org` instead (it reaches the same
52
+ tunnel). Every link and `COOKIE_DOMAIN` must be on one domain, or the sign-in
53
+ cookie is dropped as third-party and the app shows you signed out.
54
+ - `NEXT_PUBLIC_COOKIE_PREFIX` — keep it different from production's.
55
+ `.env.example` already ships a distinct value.
50
56
 
51
57
  ## Stop sharing
52
58
 
@@ -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
- }