@xingular/harness 1.3.1-unstable.8 → 1.4.0-unstable

package/dist/sdk/accounts/accounts.d.ts

@@ -18,6 +18,8 @@ export interface ModelOption {
 type Credential = Record<string, unknown> & {
     type: 'api_key' | 'oauth';
 };
+/** How long a terminal may hold a provider's credential lock; shorter than another waiter's lock timeout. */
+export declare const CREDENTIAL_LEASE_MS = 20000;
 export interface AccountLoginSnapshot {
     accountId: string;
     loginId: string;
@@ -45,10 +47,10 @@ export declare class Accounts {
     private readonly runtimes;
     private readonly logins;
     private readonly latestLogins;
-    /** How many of this process's terminals use each account's auth.json. */
+    /** How many of this process's terminals run on each account. */
     private readonly terminals;
-    /** The credentials this process wrote to, or found in, each account's auth.json when its first terminal began. */
-    private readonly terminalSnapshots;
+    /** Open credential leases: a terminal holds a provider's lock while its Pi refreshes or signs in. */
+    private readonly leases;
     private installationDeviceIdPromise;
     /**
      * Lets the limits service observe each account runtime's provider responses. The Harness sets
@@ -79,6 +81,18 @@ export declare class Accounts {
     }[]>;
     /** Pi and explicit account edits share the same cross-process credential lock. */
     private credentialStore;
+    /**
+     * Takes a provider's cross-process credential lock for a terminal whose Pi will refresh or sign in
+     * with the current credential, and holds it until `commitCredentialLease` or `CREDENTIAL_LEASE_MS`.
+     * A terminal reads and writes credentials only this way, so one refresh token has one lock: two
+     * copies refreshed under separate locks made the second refresh fail with `invalid_grant`.
+     */
+    leaseCredential(accountId: string, provider: string, timeoutMs?: number): Promise<{
+        leaseId: string;
+        current: Credential | undefined;
+    }>;
+    /** Ends a lease, storing `credential` when one is given. Resolves with the stored credential afterwards. */
+    commitCredentialLease(accountId: string, leaseId: string, credential?: Credential): Promise<Credential | undefined>;
     /** Pi's OAuth device ID belongs to this Harness installation, not to one isolated account. */
     installationDeviceId(): Promise<string>;
     private loadInstallationDeviceId;
@@ -138,30 +152,22 @@ export declare class Accounts {
     loginStatus(accountId: string): AccountLoginSnapshot | null;
     loginRespond(loginId: string, promptId: string, value: string | null): void;
     loginCancel(accountId: string, loginId?: string | null): void;
-    /**
-     * The `pi` command reads `auth.json` from its agent folder. For a terminal session the
-     * account's stored credentials are written there (mode 0600) while the terminal runs, then
-     * read back and removed.
-     */
     /** How many terminal sessions are running on this account right now. */
     terminalCount(accountId: string): number;
     /**
-     * Starts a terminal's use of the account's auth.json. The file is written from the store when the
-     * first terminal of the account begins. While another process's terminal still uses it, the tokens
-     * already in the file stay, because that terminal may have refreshed them; only a provider the file
-     * lacks is added from the store, so a key saved after the other terminal began still reaches this one.
+     * Starts a terminal on the account. Its Pi reads and writes credentials through this store over
+     * the terminal's control socket (`accounts.credentials.*`), so nothing is written to `auth.json`.
+     * A file an older terminal left is folded into the store, newest token first.
      */
     terminalBegin(account: Account): Promise<void>;
+    /** Ends a terminal on the account; the last one in this process folds in any `auth.json` left behind. */
+    terminalEnd(account: Account): Promise<void>;
     /**
-     * Ends a terminal's use of the auth.json. Each terminal saves what its Pi changed since it began (a
-     * refreshed or new sign-in, or a provider it signed out of), even while another process still uses the
-     * file, so no refresh is lost when the other terminal ends first. A credential saved to the store after
-     * the terminal began is in neither the file nor the snapshot, so it stays. The last terminal of the
-     * account to end, in every process, removes the file.
+     * Saves what an older terminal's `auth.json` holds that the store lacks or holds older, under each
+     * provider's lock, and never replaces a newer token. The file is removed once no other process has
+     * a terminal on the account, since an older one may still be reading it.
      */
-    terminalEnd(account: Account): Promise<void>;
-    /** The account's stored credentials, with `existing` kept as it is for every provider it already has. */
-    private storedCredentials;
+    private adoptAuthFile;
     /**
      * Whether another live process has a terminal on this account. Lease files of processes that have
      * ended are removed, so a crash never leaves the account looking busy.

package/dist/sdk/accounts/accounts.js

@@ -1,7 +1,7 @@
 // The accounts service: everything that needs the secret store, the Pi runtime, or a notice.
 // Credentials go to the embedding application's secret store; nothing here writes one to the
-// harness's own files, except a terminal session's `auth.json` while that terminal runs.
-import { chmodSync, existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
+// harness's own files. A terminal's Pi reaches them through `accounts.credentials.*`.
+import { existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { join } from 'node:path';
 import { log } from "../core/bus.js";
@@ -55,6 +55,23 @@ function sameCredential(a, b) {
         return false;
     return JSON.stringify(a, Object.keys(a).sort()) === JSON.stringify(b, Object.keys(b).sort());
 }
+/**
+ * Whether a credential found outside the store should replace the stored one. The store is the
+ * truth; an OAuth token wins only when it expires later, because OpenAI and others rotate the
+ * refresh token on every refresh and an older one is already spent.
+ */
+function preferCredential(candidate, stored) {
+    if (!stored)
+        return true;
+    if (sameCredential(candidate, stored))
+        return false;
+    if (candidate.type !== 'oauth' || stored.type !== 'oauth')
+        return false;
+    const expires = (credential) => typeof credential.expires === 'number' ? credential.expires : 0;
+    return expires(candidate) > expires(stored);
+}
+/** How long a terminal may hold a provider's credential lock; shorter than another waiter's lock timeout. */
+export const CREDENTIAL_LEASE_MS = 20_000;
 function validProvider(provider) {
     if (provider && provider.length <= 64 && /^[A-Za-z0-9._-]+$/.test(provider))
         return provider;
@@ -68,10 +85,10 @@ export class Accounts {
     runtimes = new Map();
     logins = new Map();
     latestLogins = new Map();
-    /** How many of this process's terminals use each account's auth.json. */
+    /** How many of this process's terminals run on each account. */
     terminals = new Map();
-    /** The credentials this process wrote to, or found in, each account's auth.json when its first terminal began. */
-    terminalSnapshots = new Map();
+    /** Open credential leases: a terminal holds a provider's lock while its Pi refreshes or signs in. */
+    leases = new Map();
     installationDeviceIdPromise = null;
     /**
      * Lets the limits service observe each account runtime's provider responses. The Harness sets
@@ -178,6 +195,51 @@ export class Accounts {
             delete: (providerId) => this.writeCredential(accountId, providerId, null)
         };
     }
+    /**
+     * Takes a provider's cross-process credential lock for a terminal whose Pi will refresh or sign in
+     * with the current credential, and holds it until `commitCredentialLease` or `CREDENTIAL_LEASE_MS`.
+     * A terminal reads and writes credentials only this way, so one refresh token has one lock: two
+     * copies refreshed under separate locks made the second refresh fail with `invalid_grant`.
+     */
+    async leaseCredential(accountId, provider, timeoutMs = CREDENTIAL_LEASE_MS) {
+        this.find(accountId);
+        const name = validProvider(provider);
+        const leaseId = randomUUID();
+        let grant;
+        const granted = new Promise((resolve) => { grant = resolve; });
+        let commit;
+        const committed = new Promise((resolve) => { commit = resolve; });
+        const done = this.modifyCredential(accountId, name, async (current) => {
+            grant(current);
+            // An abandoned lease changes nothing.
+            const timer = setTimeout(() => commit(undefined), timeoutMs);
+            timer.unref?.();
+            try {
+                return await committed;
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }).finally(() => this.leases.delete(leaseId));
+        this.leases.set(leaseId, { accountId, commit, done });
+        // The lock can fail (a wait timeout) before it is granted; once granted, how it ends is the commit's concern.
+        const ended = done.then(() => { throw new Error('The credential lease ended before it was granted.'); });
+        ended.catch(() => undefined);
+        const current = await Promise.race([granted, ended]);
+        return { leaseId, current };
+    }
+    /** Ends a lease, storing `credential` when one is given. Resolves with the stored credential afterwards. */
+    async commitCredentialLease(accountId, leaseId, credential) {
+        const lease = this.leases.get(leaseId);
+        if (!lease || lease.accountId !== accountId)
+            throw new HarnessError('not_found', 'That credential lease has ended.');
+        if (credential !== undefined && (!credential || typeof credential !== 'object' || (credential.type !== 'oauth' && credential.type !== 'api_key'))) {
+            lease.commit(undefined);
+            throw invalid('Invalid credential.');
+        }
+        lease.commit(credential);
+        return lease.done;
+    }
     /** Pi's OAuth device ID belongs to this Harness installation, not to one isolated account. */
     installationDeviceId() {
         if (!this.installationDeviceIdPromise) {
@@ -570,55 +632,31 @@ export class Accounts {
         store.audit(this.dir, accountId, 'login.cancelled', '');
     }
     // ---- Terminal sessions --------------------------------------------------------------------
-    /**
-     * The `pi` command reads `auth.json` from its agent folder. For a terminal session the
-     * account's stored credentials are written there (mode 0600) while the terminal runs, then
-     * read back and removed.
-     */
     /** How many terminal sessions are running on this account right now. */
     terminalCount(accountId) {
         return this.terminals.get(accountId) ?? 0;
     }
     /**
-     * Starts a terminal's use of the account's auth.json. The file is written from the store when the
-     * first terminal of the account begins. While another process's terminal still uses it, the tokens
-     * already in the file stay, because that terminal may have refreshed them; only a provider the file
-     * lacks is added from the store, so a key saved after the other terminal began still reaches this one.
+     * Starts a terminal on the account. Its Pi reads and writes credentials through this store over
+     * the terminal's control socket (`accounts.credentials.*`), so nothing is written to `auth.json`.
+     * A file an older terminal left is folded into the store, newest token first.
      */
     async terminalBegin(account) {
         const count = (this.terminals.get(account.id) ?? 0) + 1;
         this.terminals.set(account.id, count);
         if (count > 1)
             return;
-        const path = join(env.configDir(this.dir, account), 'auth.json');
-        let shared = false;
         try {
-            shared = this.otherTerminalProcesses(account.id);
             this.claimLease(account.id);
-            const existing = shared && existsSync(path) ? readAuth(path) : null;
-            const data = await this.storedCredentials(account.id, existing ?? {});
-            if (!existing || Object.keys(data).length > Object.keys(existing).length) {
-                atomicWrite(path, JSON.stringify(data, null, 2));
-                chmodSync(path, 0o600);
-            }
-            this.terminalSnapshots.set(account.id, data);
+            await this.adoptAuthFile(account);
         }
         catch (error) {
             this.terminals.delete(account.id);
-            this.terminalSnapshots.delete(account.id);
             this.releaseLease(account.id);
-            if (!shared)
-                rmSync(path, { force: true });
             throw error;
         }
     }
-    /**
-     * Ends a terminal's use of the auth.json. Each terminal saves what its Pi changed since it began (a
-     * refreshed or new sign-in, or a provider it signed out of), even while another process still uses the
-     * file, so no refresh is lost when the other terminal ends first. A credential saved to the store after
-     * the terminal began is in neither the file nor the snapshot, so it stays. The last terminal of the
-     * account to end, in every process, removes the file.
-     */
+    /** Ends a terminal on the account; the last one in this process folds in any `auth.json` left behind. */
     async terminalEnd(account) {
         const remaining = Math.max(0, (this.terminals.get(account.id) ?? 1) - 1);
         if (remaining > 0) {
@@ -626,45 +664,44 @@ export class Accounts {
             return;
         }
         this.terminals.delete(account.id);
-        const snapshot = this.terminalSnapshots.get(account.id) ?? {};
-        this.terminalSnapshots.delete(account.id);
         this.releaseLease(account.id);
+        await this.adoptAuthFile(account);
+    }
+    /**
+     * Saves what an older terminal's `auth.json` holds that the store lacks or holds older, under each
+     * provider's lock, and never replaces a newer token. The file is removed once no other process has
+     * a terminal on the account, since an older one may still be reading it.
+     */
+    async adoptAuthFile(account) {
         const path = join(env.configDir(this.dir, account), 'auth.json');
+        if (!existsSync(path))
+            return;
         const data = readAuth(path);
-        if (data) {
-            let changed = false;
-            for (const provider of new Set([...Object.keys(snapshot), ...Object.keys(data)])) {
-                if (provider in data) {
-                    if (sameCredential(data[provider], snapshot[provider]))
-                        continue;
-                    await this.writeCredential(account.id, provider, data[provider]).catch(() => undefined);
-                    changed = true;
-                }
-                else if (provider in snapshot) {
-                    await this.writeCredential(account.id, provider, null).catch(() => undefined);
+        if (!data)
+            throw new Error(`The terminal credential file ${path} is not readable.`);
+        let changed = false;
+        for (const [provider, candidate] of Object.entries(data)) {
+            if (!candidate || typeof candidate !== 'object' || (candidate.type !== 'oauth' && candidate.type !== 'api_key'))
+                continue;
+            try {
+                await this.modifyCredential(account.id, provider, async (stored) => {
+                    if (!preferCredential(candidate, stored))
+                        return undefined;
                     changed = true;
-                }
+                    return candidate;
+                });
             }
-            if (changed) {
-                this.invalidate(account.id);
-                store.audit(this.dir, account.id, 'credentials.synced', 'Pi terminal sign-in saved to the Keychain.');
+            catch (error) {
+                log('terminal credentials', `${provider}: ${error instanceof Error ? error.message : String(error)}`);
             }
         }
+        if (changed) {
+            this.invalidate(account.id);
+            store.audit(this.dir, account.id, 'credentials.synced', 'A terminal sign-in from auth.json was saved to the Keychain.');
+        }
         if (!this.otherTerminalProcesses(account.id))
             rmSync(path, { force: true });
     }
-    /** The account's stored credentials, with `existing` kept as it is for every provider it already has. */
-    async storedCredentials(accountId, existing) {
-        const data = { ...existing };
-        for (const provider of store.loadState(this.dir, accountId).piProviders) {
-            if (provider in data)
-                continue;
-            const credential = await this.readCredential(accountId, provider).catch(() => null);
-            if (credential)
-                data[provider] = credential;
-        }
-        return data;
-    }
     /**
      * Whether another live process has a terminal on this account. Lease files of processes that have
      * ended are removed, so a crash never leaves the account looking busy.

package/dist/sdk/agents/builtin.js

@@ -27,6 +27,7 @@ export const BUILTIN_PROFILES = [
             '- Search broadly first, then read the parts that matter.',
             '- Keep a todo list with todo_write when the search has several parts, and name your session with session_name.',
             '- Cite what you found as path:line.',
+            '- If the brief needs a tool you do not have (running tests or commands, editing), say so in your first line, then answer what you can by reading.',
             '- Return conclusions, not file dumps: what you found, where, and how sure you are.'
         ].join('\n'),
         tools: ['read', 'grep', 'find', 'ls', ...PROGRESS, ...RECALL, ...WEB],
@@ -40,6 +41,7 @@ export const BUILTIN_PROFILES = [
             'You investigate the bounded research question in your brief and return concise, evidence-backed findings to the parent.',
             '- Use read-only repository and public-web sources. Never modify files, run commands, call connected apps, or ask the user.',
             '- Prefer primary sources. Cite repository claims as path:line and external claims with source URLs.',
+            '- If the brief needs a tool you do not have (running tests or commands, editing), say so in your first line, then answer what you can by reading.',
             '- Separate observed facts from inference, state uncertainty, and return only findings relevant to the brief; do not implement.'
         ].join('\n'),
         tools: ['read', 'grep', 'find', 'ls', ...PROGRESS, ...RECALL, ...WEB],

package/dist/sdk/commands/registry.d.ts

@@ -30,6 +30,13 @@ export declare const CORE_COMMANDS: readonly [{
     readonly group: "Run";
     readonly kind: "session";
     readonly methods: readonly ["sessions.run"];
+}, {
+    readonly name: "goal";
+    readonly args: "[<objective>|edit|pause|resume|clear]";
+    readonly description: "Set or view a goal for a long-running task: /goal <objective>";
+    readonly group: "Run";
+    readonly kind: "session";
+    readonly methods: readonly ["sessions.run"];
 }, {
     readonly name: "btw";
     readonly aliases: readonly ["side"];

package/dist/sdk/commands/registry.js

@@ -4,6 +4,7 @@
 export const CORE_COMMANDS = [
     { name: 'help', description: 'List the commands', group: 'Core', kind: 'local' },
     { name: 'plan', args: '[brief]', description: 'Plan one request, read-only: /plan <brief>', group: 'Run', kind: 'session', methods: ['sessions.run'] },
+    { name: 'goal', args: '[<objective>|edit|pause|resume|clear]', description: 'Set or view a goal for a long-running task: /goal <objective>', group: 'Run', kind: 'session', methods: ['sessions.run'] },
     { name: 'btw', aliases: ['side'], args: '[question]', description: 'Ask a side question without interrupting: /btw <question>', group: 'Run', kind: 'session', methods: ['sideQuestions.start', 'sideQuestions.cancel'] },
     { name: 'new', description: 'Start a new session', group: 'Session', kind: 'session' },
     { name: 'stop', description: 'Stop the current reply', group: 'Run', kind: 'session', methods: ['runs.interrupt'] },

package/dist/sdk/core/commandBudget.js

@@ -12,11 +12,16 @@ export function resolveCommandTimeout(requested, reason) {
     const why = typeof reason === 'string' ? reason.trim() : '';
     if (typeof requested !== 'number' || !Number.isFinite(requested))
         return { ok: true, timeout: DEFAULT_COMMAND_TIMEOUT_SECONDS };
-    const timeout = Math.floor(requested);
+    let timeout = Math.floor(requested);
     if (timeout < 1)
         return { ok: false, message: 'timeout must be a positive number of seconds.' };
+    // Some models send milliseconds (Claude Code's own bash tool takes them; GPT 6 Luna sends 120000).
+    // A value that only fits as milliseconds is read as milliseconds, instead of refusing every
+    // command that model sends.
+    if (timeout > COMMAND_TIMEOUT_MAX_SECONDS && timeout >= 1_000 && timeout / 1_000 <= COMMAND_TIMEOUT_MAX_SECONDS)
+        timeout = Math.ceil(timeout / 1_000);
     if (timeout > COMMAND_TIMEOUT_MAX_SECONDS)
-        return { ok: false, message: `A command may run for at most ${COMMAND_TIMEOUT_MAX_SECONDS} seconds. Split it into smaller commands.` };
+        return { ok: false, message: `timeout is in seconds, and a command may run for at most ${COMMAND_TIMEOUT_MAX_SECONDS} seconds. Split it into smaller commands.` };
     if (timeout > COMMAND_TIMEOUT_CEILING_SECONDS && !why) {
         return { ok: false, message: `A command over ${COMMAND_TIMEOUT_CEILING_SECONDS} seconds needs a reason: pass reason with why it cannot be narrowed or run in smaller steps.` };
     }

package/dist/sdk/core/workspaceWriteOperations.d.ts

@@ -30,4 +30,28 @@ export declare const workspaceEditOperations: {
 };
 /** Binds one policy-approved path and abort signal to Pi's native write/edit operation. */
 export declare function withWorkspaceWriteAuthorization<T>(tool: T, authorizations: Map<string, WorkspaceWriteAuthorization>): T;
+interface PromptMetadata {
+    promptSnippet?: string;
+    promptGuidelines?: string[];
+}
+/** The part of Pi's tool factories the workspace file tools use. Structural, so this module needs no Pi import. */
+export interface FileToolFactories<W, E> {
+    createWriteTool(cwd: string, options: {
+        operations: typeof workspaceWriteOperations;
+    }): W;
+    createWriteToolDefinition(cwd: string, options: {
+        operations: typeof workspaceWriteOperations;
+    }): PromptMetadata;
+    createEditTool(cwd: string, options: {
+        operations: typeof workspaceEditOperations;
+    }): E;
+    createEditToolDefinition(cwd: string, options: {
+        operations: typeof workspaceEditOperations;
+    }): PromptMetadata;
+}
+/** Pi's native `write` and `edit`, routed through the workspace operations and per-call authorization. */
+export declare function createWorkspaceFileTools<W, E>(pi: FileToolFactories<W, E>, cwd: string, authorizations: Map<string, WorkspaceWriteAuthorization>): {
+    write: W;
+    edit: E;
+};
 export {};

package/dist/sdk/core/workspaceWriteOperations.js

@@ -222,3 +222,24 @@ export function withWorkspaceWriteAuthorization(tool, authorizations) {
         }
     };
 }
+/**
+ * Pi's `createWriteTool` and `createEditTool` drop the definition's prompt line and guidelines, and Pi
+ * lists only tools with a prompt line in the system prompt. Without them the model is told it has
+ * only `read` and `bash`, and edits files through shell scripts. Pi's `createBashTool` restores them
+ * the same way.
+ */
+function withPromptMetadata(tool, definition) {
+    return Object.assign(tool, {
+        promptSnippet: definition.promptSnippet,
+        promptGuidelines: definition.promptGuidelines
+    });
+}
+/** Pi's native `write` and `edit`, routed through the workspace operations and per-call authorization. */
+export function createWorkspaceFileTools(pi, cwd, authorizations) {
+    const writeOptions = { operations: workspaceWriteOperations };
+    const editOptions = { operations: workspaceEditOperations };
+    return {
+        write: withWorkspaceWriteAuthorization(withPromptMetadata(pi.createWriteTool(cwd, writeOptions), pi.createWriteToolDefinition(cwd, writeOptions)), authorizations),
+        edit: withWorkspaceWriteAuthorization(withPromptMetadata(pi.createEditTool(cwd, editOptions), pi.createEditToolDefinition(cwd, editOptions)), authorizations)
+    };
+}

package/dist/sdk/plugins/builtin.js

@@ -2,8 +2,6 @@
 import { CONNECTION_TOOLS, NATIVE_GROUP } from "../prompt/compile.js";
 import { ASK_USER, askUserTool } from "../tools/askUser.js";
 import { TODO_WRITE, todoTool } from "../tools/todo.js";
-import { CHECKPOINT_WRITE, checkpointTool } from "../tools/checkpoint.js";
-import { sliceOf } from "../sessions/workSlice.js";
 import { SPAWN_SUBAGENT, WAIT_SUBAGENTS } from "../sessions/subagents.js";
 import { subagentTools } from "../tools/spawnSubagent.js";
 import { SESSION_NAME } from "../tools/sessionName.js";
@@ -81,7 +79,6 @@ const WIKI_PLUGIN = {
 const HISTORY_PLUGIN = { id: 'history', title: 'History', description: 'Search earlier conversations and inspect recorded run trajectories.', required: 'Earlier runs are how an agent picks up where work stopped.', tools: tools([...RECALL_TOOLS, ...TRAJECTORY_TOOLS]), toolGroups: ['History'] };
 const ASK_USER_PLUGIN = { id: 'ask-user', title: 'Ask the user', description: 'Lets the agent stop and ask a question with choices.', required: 'An agent must be able to stop and ask you.', tools: [{ name: ASK_USER }] };
 const TODO_PLUGIN = { id: 'todo', title: 'Todo', description: 'Lets the agent keep a todo list of the steps of its work, recorded with the run so progress can be shown and picked up again.', required: 'Progress of longer work is kept through it.', tools: [{ name: TODO_WRITE, description: 'Write the todo list' }] };
-const CHECKPOINT_PLUGIN = { id: 'checkpoint', title: 'Checkpoint', description: 'Lets a bounded reply record a handoff at a work-slice boundary so the next slice starts from it.', required: 'A reply that stops at its budget leaves the state the next one resumes from.', tools: [{ name: CHECKPOINT_WRITE, description: 'Write the handoff checkpoint' }] };
 const CONNECTED_APPS_PLUGIN = {
     id: 'connected-apps',
     title: 'Connected apps',
@@ -133,7 +130,6 @@ export const BUILTIN_PLUGIN_REGISTRY = createBuiltinPluginRegistry([
     },
     { descriptor: ASK_USER_PLUGIN, toolOrder: 40, tools: context => context.harnessTools && context.allowedTools.includes(ASK_USER) ? [askUserTool(context.run)] : [] },
     { descriptor: TODO_PLUGIN, toolOrder: 50, tools: context => context.harnessTools ? [todoTool(context.run)] : [] },
-    { descriptor: CHECKPOINT_PLUGIN, toolOrder: 51, tools: context => context.harnessTools && context.allowedTools.includes(CHECKPOINT_WRITE) ? [checkpointTool(context.run, () => sliceOf(context.env.root, context.runId))] : [] },
     {
         descriptor: CONNECTED_APPS_PLUGIN,
         toolOrder: 0,

package/dist/sdk/plugins/discover.js

@@ -2,7 +2,7 @@
 // rules. Resolving reads folders and manifests; it never runs an extension.
 import { existsSync, lstatSync, readdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join, sep } from 'node:path';
+import { basename, join, sep } from 'node:path';
 import { log } from "../core/bus.js";
 import * as frontmatter from "../core/frontmatter.js";
 import { loadPi } from "../pi/runtime.js";
@@ -46,6 +46,50 @@ export function packageProfiles(root, folder) {
     return profiles;
 }
 const inside = (path, parent) => path === parent || path.startsWith(parent.endsWith(sep) ? parent : `${parent}${sep}`);
+/** At most this many skills are read from one package's foreign manifest. */
+const MAX_MANIFEST_SKILLS = 100;
+/**
+ * The skills a package's foreign manifest declares: a folder with a `SKILL.md`, a folder of skill
+ * folders, or a `SKILL.md` file. Paths are already relative and inside the package.
+ */
+function declaredSkillFiles(root, declared) {
+    const found = new Set();
+    const visit = (path, depth) => {
+        if (found.size >= MAX_MANIFEST_SKILLS)
+            return;
+        let stat;
+        try {
+            stat = lstatSync(path);
+        }
+        catch {
+            return;
+        }
+        if (stat.isSymbolicLink())
+            return;
+        if (stat.isFile()) {
+            if (basename(path) === 'SKILL.md')
+                found.add(path);
+            return;
+        }
+        if (!stat.isDirectory() || depth > 2)
+            return;
+        const own = join(path, 'SKILL.md');
+        try {
+            if (lstatSync(own).isFile()) {
+                found.add(own);
+                return;
+            }
+        }
+        catch {
+            // A folder without its own SKILL.md lists the skills inside it.
+        }
+        for (const name of readdirSync(path).sort())
+            visit(join(path, name), depth + 1);
+    };
+    for (const path of declared)
+        visit(join(root, path), 0);
+    return [...found];
+}
 function origin(path, metadata) {
     if (path.startsWith(BUILTIN_PREFIX))
         return 'builtin';
@@ -122,11 +166,24 @@ export const piResolver = async ({ cwd, agentDir, install, packages }) => {
     // A package may name a hooks file for the harness. Only a package a person installed counts:
     // a working folder's package cannot put code into the harness's own process.
     const roots = new Map();
-    for (const configured of manager().listConfiguredPackages())
-        if (configured.scope === 'user' && configured.installedPath)
+    // A foreign manifest's skills are text, so a project's package may bring them too.
+    const skillRoots = new Map();
+    const filtered = new Set();
+    for (const entry of [...(settings.getGlobalSettings().packages ?? []), ...(settings.getProjectSettings().packages ?? [])]) {
+        if (entry && typeof entry === 'object' && Array.isArray(entry.skills))
+            filtered.add(entry.source);
+    }
+    for (const configured of manager().listConfiguredPackages()) {
+        if (!configured.installedPath)
+            continue;
+        if (configured.scope === 'user')
             roots.set(configured.installedPath, configured.source);
-    for (const folder of packages ?? [])
+        skillRoots.set(configured.installedPath, { source: configured.source, project: configured.scope === 'project' });
+    }
+    for (const folder of packages ?? []) {
         roots.set(folder, folder);
+        skillRoots.set(folder, { source: folder, project: false });
+    }
     for (const [root, source] of roots) {
         const manifest = packageManifest(root);
         for (const path of packageProfiles(root, manifest.agents))
@@ -141,6 +198,25 @@ export const piResolver = async ({ cwd, agentDir, install, packages }) => {
         if (fallback !== -1)
             found.splice(fallback, 1);
     }
+    // Skills a foreign manifest declares load with the package, under its own switch. A package
+    // whose settings entry names skill patterns has expressed a filter, so nothing is added there.
+    for (const [root, meta] of skillRoots) {
+        if (filtered.has(meta.source))
+            continue;
+        let added = false;
+        for (const path of declaredSkillFiles(root, packageManifest(root).skills)) {
+            if (found.some((item) => item.kind === 'skill' && item.path === path))
+                continue;
+            found.push({ kind: 'skill', path, origin: 'package', project: meta.project, packageRoot: root, source: meta.source, enabled: true });
+            added = true;
+        }
+        if (!added)
+            continue;
+        // The package has resources of its own, so it is not itself an extension.
+        const fallback = found.findIndex((item) => item.kind === 'extension' && item.path === root);
+        if (fallback !== -1)
+            found.splice(fallback, 1);
+    }
     // Pi reads these itself, whatever else is switched off. They are text, so they are only listed.
     const context = [
         ...pi.loadProjectContextFiles({ cwd, agentDir }).map((file) => file.path),

package/dist/sdk/plugins/install.js

@@ -12,11 +12,37 @@ import { loadPi } from "../pi/runtime.js";
 import { ensureAdopted, list } from "./api.js";
 import * as attachments from "./attachments.js";
 import { withoutInstallScripts } from "./discover.js";
+/**
+ * A code-hosting page for a folder or file inside a repository. Pi installs a repository, so a
+ * pasted `tree` or `blob` address must not reach the package manager as one.
+ */
+function repositoryPage(source) {
+    let url;
+    try {
+        url = new URL(source);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:')
+        return null;
+    const host = url.hostname.replace(/^www\./, '');
+    const parts = url.pathname.split('/').filter(Boolean);
+    const repository = () => `${url.protocol}//${host}/${parts[0]}/${parts[1]}`;
+    if (host === 'github.com' && parts.length >= 4 && (parts[2] === 'tree' || parts[2] === 'blob'))
+        return repository();
+    if (host === 'gitlab.com' && parts.length >= 5 && parts[2] === '-' && (parts[3] === 'tree' || parts[3] === 'blob'))
+        return repository();
+    return null;
+}
 /** A folder on this machine, or a package as Pi's settings name it. A bare name is an npm package. */
 export function normalizeSource(input) {
     const source = input.trim();
     if (!source)
         throw invalid('Name a package: a folder, an npm name, or a git address.');
+    const page = repositoryPage(source);
+    if (page)
+        throw invalid(`That address is a page inside a repository, not a package. Install ${page} as a package, or copy its skill folder into <project>/.agents/skills/ for one project or ~/.agents/skills/ for every project.`);
     if (source.startsWith('~/'))
         return join(process.env.HOME || homedir(), source.slice(2));
     if (isAbsolute(source))

package/dist/sdk/plugins/manifest.d.ts

@@ -13,6 +13,8 @@ export interface PackageManifest {
     hooks: string | null;
     /** The folder of subagent profiles, inside the package. `agents` unless the manifest names another. */
     agents: string;
+    /** Skill folders a foreign manifest declares, relative to the package root. */
+    skills: string[];
     /** Data-only remote connector forms. Invalid templates are ignored; none can carry credentials. */
     connectorTemplates: ConnectorTemplate[];
 }