@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 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). It inherits
12
- `AGENTS.md` instructions from the current directory and its ancestors, and
13
- skills from `.agents/skills/` up to the repository root, following Pi's project
14
- trust rules. Shared skills and native `.pi/` configuration work normally.
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
- ## Directory settings
63
+ ## Settings
63
64
 
64
- Edit `.locus/settings.json`. All fields start empty and are optional.
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
- | Field | Value |
70
+ | Local field | Effect |
67
71
  |---|---|
68
- | `model` | Pi model reference, such as `provider/model-id`. |
69
- | `thinking` | Pi reasoning level, such as `medium` or `high`. |
70
- | `customInstructions` | Text or an existing file path, added to the Locus system prompt. |
71
- | `tools` | Tool names; plain names replace defaults, `+grep` adds a tool. |
72
- | `skills` | Extra skill file/directory paths beyond automatic discovery. |
73
- | `preloadSkills` | Skill file paths whose full instructions are always included in context. |
74
-
75
- Blank values inherit normal Pi settings and saved-session defaults. Paths are
76
- relative to the working directory; skill paths also accept `~/`. Explicit CLI
77
- model, thinking, and tool options override these settings. Restart Locus after
78
- editing this file. `system-prompt.md` in the package defines the shared identity;
79
- `settings.template.json` defines the initial settings.
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 path = join(state, 'settings.json');
38
- if (!existsSync(path)) writeFileSync(path, readFileSync(template), { flag: 'wx' });
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 path = join(state, 'settings.json');
84
+ const settingsPath = join(state, 'settings.json');
45
85
  const args = [];
46
86
  try {
47
- const profile = existsSync(path) ? readObject(path) : {};
48
- for (const [key, value] of Object.entries(profile)) {
49
- if (['model', 'thinking', 'customInstructions'].includes(key)) {
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(key === 'customInstructions' ? '--append-system-prompt' : `--${key}`, value);
52
- } else if (['tools', 'skills', 'preloadSkills'].includes(key)) {
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 === 'tools') {
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
- const skill = resolve(directory, entry.startsWith('~/') ? join(homedir(), entry.slice(2)) : entry);
60
- args.push('--skill', skill);
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: ${skill}\nResolve its relative references from ${dirname(skill)}.\n\n${readFileSync(skill, 'utf8')}`);
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 .locus/settings.json: ${error.message}`);
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
- Profile: .locus/settings.json | History: .locus/session.jsonl
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@granawkins/locus",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "The patron saint of a directory: one persistent Pi conversation and its working files.",
5
5
  "license": "MIT",
6
6
  "author": "granawkins",
@@ -1,8 +1,3 @@
1
1
  {
2
- "model": "",
3
- "thinking": "",
4
- "customInstructions": "",
5
- "tools": [],
6
- "skills": [],
7
- "preloadSkills": []
2
+ "contextFiles": { "include": [], "exclude": [] }
8
3
  }
@@ -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
- - `.locus/settings.json` controls model, thinking, tools, extra skill paths,
28
- preloaded skill file paths, and additive instructions. Empty values inherit
29
- defaults. Restart after edits; never edit Pi's session files.
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.