@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/DISCLOSURE +174 -0
- package/README.md +36 -16
- package/dist/cli.js +84643 -50754
- 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 +29 -16
- package/plugin/factiii/bin/factiii-board-mcp +11 -3
- package/plugin/factiii/bin/factiii-secrets +88 -21
- package/plugin/factiii/bin/session-context.sh +55 -2
- package/plugin/factiii/skills/board-sessions/SKILL.md +74 -0
- package/plugin/factiii/skills/factiii-secrets/SKILL.md +21 -7
- 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 +12 -6
- package/index/image-package.json +0 -8
- package/index/index.js +0 -105575
- package/native/screenhost.m +0 -500
- 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
package/package.json
CHANGED
|
@@ -1,9 +1,14 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@factiii/runner",
|
|
3
|
-
"version": "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": "
|
|
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
|
-
"
|
|
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
|
-
"
|
|
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
|
-
"
|
|
50
|
-
"
|
|
51
|
-
"
|
|
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": "^
|
|
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
|
|
120
|
-
//
|
|
121
|
-
|
|
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.
|
|
9
|
-
*
|
|
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
|
-
|
|
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.
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
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
|
|
317
|
-
//
|
|
318
|
-
//
|
|
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
|
-
|
|
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
|
|
340
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
@@ -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
|
-
##
|
|
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
|
|
119
|
-
|
|
120
|
-
|
|
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
|
|
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
|
-
- `
|
|
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. 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
|
|