@granawkins/locus 0.1.0 → 0.1.1
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/README.md +52 -20
- package/bin/locus.js +92 -16
- package/package.json +1 -1
- package/settings.template.json +1 -6
- package/skills/locus/SKILL.md +5 -3
package/README.md
CHANGED
|
@@ -8,10 +8,11 @@ working artifacts kept in the directory. Locus stewards that work over time,
|
|
|
8
8
|
using Pi's built-in compaction while retaining JSONL history it can inspect.
|
|
9
9
|
|
|
10
10
|
Built on [Pi](https://pi.dev), Locus supports Pi's conversation CLI modes,
|
|
11
|
-
tools, skills, and [community extensions](https://pi.dev/packages).
|
|
12
|
-
`AGENTS.md` instructions from the current directory and its
|
|
13
|
-
skills from `.agents/skills/` up to the repository root,
|
|
14
|
-
trust rules. Shared skills and native `.pi/`
|
|
11
|
+
tools, skills, and [community extensions](https://pi.dev/packages). By default,
|
|
12
|
+
it inherits `AGENTS.md` instructions from the current directory and its
|
|
13
|
+
ancestors, and skills from `.agents/skills/` up to the repository root,
|
|
14
|
+
following Pi's project trust rules. Shared skills and native `.pi/`
|
|
15
|
+
configuration work normally.
|
|
15
16
|
|
|
16
17
|
## Install
|
|
17
18
|
|
|
@@ -50,7 +51,7 @@ The first run creates `.locus/` in the current directory:
|
|
|
50
51
|
|
|
51
52
|
| File | Purpose |
|
|
52
53
|
|---|---|
|
|
53
|
-
| `settings.json` | This directory's settings. |
|
|
54
|
+
| `settings.json` | This directory's Locus settings. |
|
|
54
55
|
| `session.jsonl` | Cumulative messages, tool results, and compaction records. |
|
|
55
56
|
| `lock` | Lock target; the active lock is maintained in `lock.lock/`. A competing run exits with code 75. |
|
|
56
57
|
|
|
@@ -59,24 +60,55 @@ recoverable after two minutes. The agent can keep notes and other working files
|
|
|
59
60
|
settings, skills, and installed packages live in `~/.locus/agent/`; override that
|
|
60
61
|
location with `LOCUS_AGENT_DIR`. There is no shared master conversation.
|
|
61
62
|
|
|
62
|
-
##
|
|
63
|
+
## Settings
|
|
63
64
|
|
|
64
|
-
|
|
65
|
+
Global Pi settings live in `~/.locus/agent/settings.json` (or
|
|
66
|
+
`LOCUS_AGENT_DIR/settings.json`); Pi supports its full settings set there.
|
|
67
|
+
Each Locus directory has `.locus/settings.json`. Locus passes these local
|
|
68
|
+
settings to Pi using CLI options:
|
|
65
69
|
|
|
66
|
-
|
|
|
70
|
+
| Local field | Effect |
|
|
67
71
|
|---|---|
|
|
68
|
-
| `
|
|
69
|
-
| `
|
|
70
|
-
| `
|
|
71
|
-
| `
|
|
72
|
-
| `
|
|
73
|
-
| `
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
72
|
+
| `defaultProvider`, `defaultModel`, `defaultThinkingLevel` | Choose the model and thinking level. A local provider needs a local or global model. |
|
|
73
|
+
| `enabledModels` | Scope available models. |
|
|
74
|
+
| `defaultTools` | Select or modify built-in tools; `[]` disables them. |
|
|
75
|
+
| `skills`, `extensions`, `prompts`, `themes` | Add resource paths. Local lists accept paths, not exclusion patterns or globs. |
|
|
76
|
+
| `theme`, `tuiMode` | Select the initial theme or terminal mode. |
|
|
77
|
+
| `contextFiles` | Include or exclude specific context files. |
|
|
78
|
+
|
|
79
|
+
`defaultTools` accepts either tool names or `+name`/`-name` modifiers; the two
|
|
80
|
+
forms cannot be mixed in one local list. An empty `enabledModels` list restores
|
|
81
|
+
all available models. Local resource paths resolve from the working directory.
|
|
82
|
+
|
|
83
|
+
Pi's other settings have no matching CLI option and are not supported in
|
|
84
|
+
`.locus/settings.json`; put them in the global file. Pi still reads its native
|
|
85
|
+
`.pi/settings.json` when present, subject to project trust. Explicit command
|
|
86
|
+
line options take precedence over Locus's local settings. Older local names
|
|
87
|
+
(`model`, `thinking`, `tools`, `customInstructions`, `preloadSkills`) remain
|
|
88
|
+
supported for existing directories; use Pi's names for new settings. Restart
|
|
89
|
+
Locus after editing settings. `system-prompt.md` defines the shared identity.
|
|
90
|
+
|
|
91
|
+
Locus reads `contextFiles.include` and `contextFiles.exclude` from both the
|
|
92
|
+
global Pi settings and local `.locus/settings.json`, combining the lists.
|
|
93
|
+
Relative global paths resolve from the agent directory; relative local paths
|
|
94
|
+
resolve from the working directory. `~/` and absolute paths also work.
|
|
95
|
+
|
|
96
|
+
When either `contextFiles` list is nonempty, Locus starts with Pi's normal
|
|
97
|
+
context-file discovery, removes excluded files, then adds included files even
|
|
98
|
+
outside that discovery path. Exclusion wins if a file appears in both lists;
|
|
99
|
+
symlinked paths are treated as the same file. Each path must name an existing
|
|
100
|
+
file. This setting does not filter other system-prompt additions. Skills are
|
|
101
|
+
unaffected. For example, a source agent can omit repository-wide instructions
|
|
102
|
+
while loading its own:
|
|
103
|
+
|
|
104
|
+
```json
|
|
105
|
+
{
|
|
106
|
+
"contextFiles": {
|
|
107
|
+
"include": ["/absolute/path/to/source/AGENTS.md"],
|
|
108
|
+
"exclude": ["/absolute/path/to/repo/AGENTS.md"]
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
```
|
|
80
112
|
|
|
81
113
|
## Use from another agent
|
|
82
114
|
|
package/bin/locus.js
CHANGED
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
import { existsSync, mkdirSync, readFileSync, writeFileSync, realpathSync } from 'node:fs';
|
|
2
|
+
import { existsSync, mkdirSync, readFileSync, writeFileSync, realpathSync, statSync } from 'node:fs';
|
|
3
3
|
import { dirname, join, resolve } from 'node:path';
|
|
4
4
|
import { homedir } from 'node:os';
|
|
5
5
|
import { spawn } from 'node:child_process';
|
|
6
6
|
import lockfile from 'proper-lockfile';
|
|
7
7
|
import { fileURLToPath } from 'node:url';
|
|
8
|
+
import { loadProjectContextFiles } from '@earendil-works/pi-coding-agent';
|
|
8
9
|
|
|
9
10
|
const template = new URL('../settings.template.json', import.meta.url);
|
|
10
11
|
|
|
@@ -34,38 +35,113 @@ export function initialize(directory) {
|
|
|
34
35
|
const state = join(directory, '.locus');
|
|
35
36
|
mkdirSync(state, { recursive: true });
|
|
36
37
|
migrateSettings(state);
|
|
37
|
-
const
|
|
38
|
-
if (!existsSync(
|
|
38
|
+
const settings = join(state, 'settings.json');
|
|
39
|
+
if (!existsSync(settings)) writeFileSync(settings, readFileSync(template), { flag: 'wx' });
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
function contextArguments(directory, selections, agentDir) {
|
|
43
|
+
const include = [], exclude = [];
|
|
44
|
+
for (const { contextFiles, base } of selections) {
|
|
45
|
+
if (!contextFiles || typeof contextFiles !== 'object' || Array.isArray(contextFiles) ||
|
|
46
|
+
Object.keys(contextFiles).some(key => !['include', 'exclude'].includes(key))) {
|
|
47
|
+
throw Error('contextFiles must contain only include and exclude lists');
|
|
48
|
+
}
|
|
49
|
+
for (const [name, paths] of Object.entries({ include: contextFiles.include ?? [], exclude: contextFiles.exclude ?? [] })) {
|
|
50
|
+
if (!Array.isArray(paths) || paths.some(path => typeof path !== 'string' || !path.trim())) {
|
|
51
|
+
throw Error(`contextFiles.${name} must be a list of nonempty paths`);
|
|
52
|
+
}
|
|
53
|
+
(name === 'include' ? include : exclude).push(...paths.map(path => ({ path, base })));
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
if (!include.length && !exclude.length) return [];
|
|
57
|
+
|
|
58
|
+
const canonical = ({ path, base }) => {
|
|
59
|
+
const resolved = resolve(base, path.startsWith('~/') ? join(homedir(), path.slice(2)) : path);
|
|
60
|
+
try {
|
|
61
|
+
if (statSync(resolved).isFile()) return realpathSync(resolved);
|
|
62
|
+
} catch (error) {
|
|
63
|
+
if (error.code !== 'ENOENT') throw error;
|
|
64
|
+
}
|
|
65
|
+
throw Error(`context file is missing or not a regular file: ${resolved}`);
|
|
66
|
+
};
|
|
67
|
+
// Pi's CLI cannot filter individual context files, so select from Pi's own discovery.
|
|
68
|
+
const omitted = new Set(exclude.map(canonical));
|
|
69
|
+
const selected = new Map();
|
|
70
|
+
for (const file of loadProjectContextFiles({ cwd: directory, agentDir })) {
|
|
71
|
+
const identity = canonical({ path: file.path, base: directory });
|
|
72
|
+
if (!omitted.has(identity)) selected.set(identity, file.path);
|
|
73
|
+
}
|
|
74
|
+
for (const entry of include) {
|
|
75
|
+
const identity = canonical(entry);
|
|
76
|
+
if (!omitted.has(identity) && !selected.has(identity)) selected.set(identity, identity);
|
|
77
|
+
}
|
|
78
|
+
return ['--no-context-files', ...[...selected.values()].flatMap(path => ['--append-system-prompt', path])];
|
|
39
79
|
}
|
|
40
80
|
|
|
41
|
-
export function profileArguments(directory) {
|
|
81
|
+
export function profileArguments(directory, agentDir = process.env.LOCUS_AGENT_DIR || join(homedir(), '.locus', 'agent')) {
|
|
42
82
|
const state = join(directory, '.locus');
|
|
43
83
|
migrateSettings(state);
|
|
44
|
-
const
|
|
84
|
+
const settingsPath = join(state, 'settings.json');
|
|
45
85
|
const args = [];
|
|
46
86
|
try {
|
|
47
|
-
const
|
|
48
|
-
|
|
49
|
-
|
|
87
|
+
const selections = [];
|
|
88
|
+
const globalPath = join(agentDir, 'settings.json');
|
|
89
|
+
const global = existsSync(globalPath) ? readObject(globalPath) : {};
|
|
90
|
+
if ('contextFiles' in global) selections.push({ contextFiles: global.contextFiles, base: agentDir });
|
|
91
|
+
const profile = existsSync(settingsPath) ? readObject(settingsPath) : {};
|
|
92
|
+
const aliases = { model: 'defaultModel', thinking: 'defaultThinkingLevel', tools: 'defaultTools' };
|
|
93
|
+
for (const [oldName, newName] of Object.entries(aliases)) {
|
|
94
|
+
if (oldName in profile && newName in profile) throw Error(`${oldName} and ${newName} cannot both be set`);
|
|
95
|
+
}
|
|
96
|
+
const provider = profile.defaultProvider;
|
|
97
|
+
if (provider !== undefined && (typeof provider !== 'string' || !provider.trim())) {
|
|
98
|
+
throw Error('defaultProvider must be a nonempty string');
|
|
99
|
+
}
|
|
100
|
+
const localModel = profile.defaultModel ?? profile.model;
|
|
101
|
+
if (provider && !localModel && !global.defaultModel) {
|
|
102
|
+
throw Error('defaultProvider requires a defaultModel locally or globally');
|
|
103
|
+
}
|
|
104
|
+
for (const [rawKey, value] of Object.entries(profile)) {
|
|
105
|
+
const key = aliases[rawKey] ?? rawKey;
|
|
106
|
+
if (key === 'defaultProvider') {
|
|
107
|
+
args.push('--provider', value);
|
|
108
|
+
if (!localModel) args.push('--model', global.defaultModel);
|
|
109
|
+
} else if (['defaultModel', 'defaultThinkingLevel', 'customInstructions', 'theme', 'tuiMode'].includes(key)) {
|
|
50
110
|
if (typeof value !== 'string') throw Error(`${key} must be a string`);
|
|
51
|
-
if (value.trim()) args.push(
|
|
52
|
-
|
|
111
|
+
if (value.trim()) args.push({ defaultModel: '--model', defaultThinkingLevel: '--thinking',
|
|
112
|
+
customInstructions: '--append-system-prompt', theme: '--use-theme', tuiMode: '--tui-mode' }[key], value);
|
|
113
|
+
} else if (key === 'contextFiles') {
|
|
114
|
+
selections.push({ contextFiles: value, base: directory });
|
|
115
|
+
} else if (['defaultTools', 'enabledModels', 'skills', 'extensions', 'prompts', 'themes', 'preloadSkills'].includes(key)) {
|
|
53
116
|
if (!Array.isArray(value) || value.some(item => typeof item !== 'string' || !item.trim())) {
|
|
54
117
|
throw Error(`${key} must be an array of nonempty strings`);
|
|
55
118
|
}
|
|
56
|
-
if (key === '
|
|
119
|
+
if (key === 'defaultTools') {
|
|
120
|
+
const modifiers = value.filter(item => /^[+-]/.test(item));
|
|
121
|
+
if (modifiers.length && modifiers.length !== value.length) {
|
|
122
|
+
throw Error('defaultTools cannot mix tool names and + or - modifiers in Locus settings');
|
|
123
|
+
}
|
|
57
124
|
if (value.length) args.push('--tools', value.join(','));
|
|
125
|
+
else if (rawKey !== 'tools') args.push('--no-builtin-tools');
|
|
126
|
+
} else if (key === 'enabledModels') {
|
|
127
|
+
args.push('--models', value.length ? value.join(',') : '*');
|
|
58
128
|
} else for (const entry of value) {
|
|
59
|
-
|
|
60
|
-
|
|
129
|
+
if (entry.startsWith('-') || entry.includes('*')) throw Error(`${key} supports paths only; use Pi settings for exclusions and globs`);
|
|
130
|
+
const resourcePath = entry.replace(/^\+/, '');
|
|
131
|
+
const resource = key === 'extensions' && resourcePath.startsWith('builtin:') ? resourcePath :
|
|
132
|
+
resolve(directory, resourcePath.startsWith('~/') ? join(homedir(), resourcePath.slice(2)) : resourcePath);
|
|
133
|
+
const option = { skills: '--skill', extensions: '--extension', prompts: '--prompt-template',
|
|
134
|
+
themes: '--theme', preloadSkills: '--skill' }[key];
|
|
135
|
+
args.push(option, resource);
|
|
61
136
|
if (key === 'preloadSkills') {
|
|
62
|
-
args.push('--append-system-prompt', `Preloaded skill: ${
|
|
137
|
+
args.push('--append-system-prompt', `Preloaded skill: ${resource}\nResolve its relative references from ${dirname(resource)}.\n\n${readFileSync(resource, 'utf8')}`);
|
|
63
138
|
}
|
|
64
139
|
}
|
|
65
140
|
} else throw Error(`unknown field: ${key}`);
|
|
66
141
|
}
|
|
142
|
+
args.push(...contextArguments(directory, selections, agentDir));
|
|
67
143
|
} catch (error) {
|
|
68
|
-
throw Error(`invalid
|
|
144
|
+
throw Error(`invalid Locus settings: ${error.message}`);
|
|
69
145
|
}
|
|
70
146
|
return args;
|
|
71
147
|
}
|
|
@@ -128,7 +204,7 @@ const help = `Usage:
|
|
|
128
204
|
Other arguments pass through to Pi. Use /login, /model, /settings, and
|
|
129
205
|
/reload inside chat. Skills and extensions use Pi's normal discovery.
|
|
130
206
|
Conversation commands initialize the current directory automatically.
|
|
131
|
-
|
|
207
|
+
Settings: ~/.locus/agent/settings.json and .locus/settings.json | History: .locus/session.jsonl
|
|
132
208
|
Requires Node.js 22.19 or newer on Linux, macOS, or Windows.`;
|
|
133
209
|
|
|
134
210
|
export async function main(args = process.argv.slice(2), directory = process.cwd()) {
|
package/package.json
CHANGED
package/settings.template.json
CHANGED
package/skills/locus/SKILL.md
CHANGED
|
@@ -24,9 +24,11 @@ Database integrations and completion evidence are project-specific.
|
|
|
24
24
|
- Bound concurrency in the caller. One process per directory is allowed;
|
|
25
25
|
competing runs exit 75. Forced termination can leave a lock stale for two
|
|
26
26
|
minutes. There is no global queue.
|
|
27
|
-
-
|
|
28
|
-
|
|
29
|
-
|
|
27
|
+
- Global `~/.locus/agent/settings.json` (or `LOCUS_AGENT_DIR/settings.json`)
|
|
28
|
+
supports Pi's full settings set. Local `.locus/settings.json` supports model,
|
|
29
|
+
thinking, tool, resource, theme, and context-file options with Pi's field
|
|
30
|
+
names. Locus combines global and local `contextFiles` lists. Restart after
|
|
31
|
+
edits; never edit Pi's session files.
|
|
30
32
|
- Pi discovers ancestor `AGENTS.md` and `.agents/skills/` (skills stop at the
|
|
31
33
|
repository root). Project resources require trust; unattended jobs need
|
|
32
34
|
saved trust or an explicit authorized `--approve` decision.
|