@matuto-ai/pi-broker-connector 0.1.0 → 0.1.2

package/README.md

@@ -28,29 +28,37 @@ Or, after the npm-scope correction PR is merged into `main`:
 pi install git:github.com/matuto-ai/pi-broker-connector
 ```
 
-This uses the default branch; wait for the scope correction to merge first. To test before merge, append `@` and the exact reviewed commit from the scope-correction PR. Existing tags are unchanged and may still contain the old npm package identity; do not use an old tag as evidence of the new scope. Publishing the new scoped npm package remains paused until source corrections are reviewed and publication is explicitly resumed.
+This uses the default branch; wait for the scope correction to merge first. To test before merge, append `@` and the exact reviewed commit from the scope-correction PR. Existing tags are unchanged and may still contain the old npm package identity; do not use an old tag as evidence of the new scope. Publish a new package version only after its source changes have been reviewed and the owner is ready to release it.
 
 ### From npm (only after publication)
 
 ```sh
-pi install npm:@matuto-ai/pi-broker-connector@0.1.0
+pi install npm:@matuto-ai/pi-broker-connector@0.1.2
 ```
 
 The proposed scope must be controlled by the publisher before publication. A repository name or workflow does not create an npm account/package. Until published, use the checkout route above; do not treat the npm command as currently available.
 
-### Connect
+### Connect — no restart or environment variable needed
 
-Mount/copy only this client's private bundle into the sandbox. Keep `connection.json` and `token` private to the sandbox's user (`0600`), and the directory `0700`. Do not paste tokens into prompts, command arguments, screenshots, Git, or shared config.
+With this version loaded, run one command **in the current Pi session**:
+
+```text
+/psst-connect /absolute/path/to/connection.json
+```
+
+Use the existing bundle path; keep its `token` next to `connection.json`. Do not copy the JSON alone. The command connects the current native session and saves **only the absolute path**, as one line in `~/.config/psst/pi-config-path`. It does not copy credentials or alter the process environment. `/reload` reads that TXT again. You can also create that TXT yourself (mode `0600`, directory `0700`) and use `/reload`.
+
+For an existing installation, after the owner publishes this version, update the package **inside the same sandbox**, then use `/reload` in the running Pi and the command above:
 
 ```sh
-export PSST_CONFIG_FILE=/absolute/private/psst/pi/connection.json
-export PSST_NAME='Pi coding'
-# Optional: a durable path INSIDE this sandbox, owned by its user, mode 0700
-export PSST_STATE_DIR=/absolute/private/psst/pi/state
-pi
+pi install npm:@matuto-ai/pi-broker-connector@0.1.2
 ```
 
-`PSST_CONFIG` is an alias; `PSST_CONFIG_FILE` wins. `PSST_NAME` defaults to `Pi`. State defaults to `~/.local/state/psst/pi`. Existing shells/processes do not inherit newly exported variables: restart Pi once with these variables, then `/reload` can retry after configuration changes. `/psst-status` displays status and the session's exact client ID.
+This installer command is not a second agent session. No sandbox recreation or Pi process restart is required. Version 0.1.1 does not have `/psst-connect`; updating the package and reloading are required first.
+
+Keep `connection.json` and `token` private to the sandbox user (`0600`), directory `0700`. Never paste tokens into prompts, command arguments, Git, or shared config. Paths must refer to real files rather than symlinks. A `/tmp` bundle works for the current container but may disappear on container removal; remembering its path does not make the bundle persistent.
+
+Existing `PSST_CONFIG_FILE` and `PSST_CONFIG` configurations remain supported: on session start/reload, precedence is `PSST_CONFIG_FILE`, then `PSST_CONFIG`, then the saved TXT. `/psst-connect` explicitly selects the path for the current instance; it warns if inherited environment settings will take precedence on the next reload. `PSST_NAME` defaults to `Pi`; `PSST_STATE_DIR` defaults to `~/.local/state/psst/pi`. `/psst-status` displays status and the session's exact client ID. Repeated connect closes the previous runtime before reopening the same session inbox; invalid input leaves the current connection untouched. Connection failures retain the selected path for `/reload` retry.
 
 Expected non-secret bundle structure, generated by the broker enrollment utility:
 
@@ -111,6 +119,8 @@ Tests cover private bundle validation, exact session isolation, duplicate owners
 
 ## Publishing
 
+The `0.1.2` patch adds current-session connection through `/psst-connect` and a saved TXT path. After this PR is merged, the owner can create a GitHub release with tag **`v0.1.2`**. Preparing this PR does not publish that release or npm version.
+
 The release workflow follows the existing Pi plugin convention: a published GitHub release triggers checks and npm publishing. It requires a `v<package.version>` tag and runs the native host gate before publishing. Nothing is published by CI on pull requests or ordinary pushes.
 
 For OIDC trusted publishing, configure the npm package's trusted publisher for GitHub owner `matuto-ai`, repo `pi-broker-connector`, workflow **`npm-publish.yml`** (filename only), allowing direct `npm publish`. No `NPM_TOKEN` is embedded or created. Use npm CLI >=11.5.1 with the supported Node version. If the npm package does not yet exist, the owner must complete the first package publication/account setup using npm's supported process before configuring its package settings. That setup is not performed by this repository. If the first manual publication uses `0.1.0`, bump the package version and matching release tag before the next automated publish; npm does not allow republishing the same version.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matuto-ai/pi-broker-connector",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Session-bound Psst broker messaging tools for Pi",
   "type": "module",
   "license": "MIT",

package/src/config-path.mjs

@@ -0,0 +1,43 @@
+import { constants, openSync, closeSync, fstatSync, readFileSync, realpathSync, mkdirSync, lstatSync, writeFileSync, renameSync, unlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { LocalError } from '../vendor/broker/reference/errors.mjs';
+
+export function validateConfigPath(value) {
+  if (typeof value !== 'string' || !isAbsolute(value) || value.length > 4096 || /[\x00-\x1f\x7f]/.test(value)) throw new LocalError('invalid_configuration');
+  return value;
+}
+
+// This TXT contains a path only, never the bundle or token.
+export function createConfigPathStore(home = homedir()) {
+  const directory = join(home, '.config', 'psst');
+  const file = join(directory, 'pi-config-path');
+  return {
+    read() {
+      let fd;
+      try {
+        try { lstatSync(file); } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+        if (realpathSync(file) !== file) throw new Error();
+        fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.size > 4097 || (stat.mode & 0o077) || (process.getuid && stat.uid !== process.getuid())) throw new Error();
+        return validateConfigPath(readFileSync(fd, 'utf8').replace(/\n$/, ''));
+      } catch { throw new LocalError('invalid_configuration'); }
+      finally { if (fd !== undefined) closeSync(fd); }
+    },
+    write(path) {
+      validateConfigPath(path);
+      let temporary;
+      try {
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+        const stat = lstatSync(directory);
+        if (realpathSync(directory) !== directory || !stat.isDirectory() || (stat.mode & 0o077) || (process.getuid && stat.uid !== process.getuid())) throw new Error();
+        temporary = join(directory, `.pi-config-path-${randomUUID()}`);
+        writeFileSync(temporary, `${path}\n`, { mode: 0o600, flag: 'wx' });
+        renameSync(temporary, file);
+      } catch { throw new LocalError('invalid_configuration'); }
+      finally { if (temporary) { try { unlinkSync(temporary); } catch {} } }
+    },
+  };
+}

package/src/config.mjs

@@ -16,9 +16,10 @@ export function readPrivateJson(path) {
   finally { if (fd !== undefined) closeSync(fd); }
 }
 
-export function readConfig(env = process.env) {
-  if (!env.PSST_CONFIG_FILE && !env.PSST_CONFIG) return null;
-  const path = resolve(env.PSST_CONFIG_FILE || env.PSST_CONFIG);
+export function readConfig(env = process.env, explicitPath) {
+  const selected = explicitPath || env.PSST_CONFIG_FILE || env.PSST_CONFIG;
+  if (!selected) return null;
+  const path = resolve(selected);
   const raw = readPrivateJson(path);
   if (raw.format !== 'broker-client-bundle-v1' || !Array.isArray(raw.allowed_client_types) || !raw.allowed_client_types.includes('pi')
       || raw.protocol_version !== '1' || raw.file_paths_relative_to !== 'connection_file_directory'

package/src/extension.mjs

@@ -1,24 +1,31 @@
+import { createConfigPathStore, validateConfigPath } from './config-path.mjs';
 import { readConfig } from './config.mjs';
 import { PiBrokerSession } from './session.mjs';
 import { createCooperativeInbox } from './cooperative-inbox.mjs';
 import { createTools, invokeTool } from '../vendor/broker/reference/tools.mjs';
 import { LocalError, safeError } from '../vendor/broker/reference/errors.mjs';
 
-export function installExtension(pi, Type, { configReader = readConfig, createSession = options => new PiBrokerSession(options) } = {}) {
+export function installExtension(pi, Type, { configReader = readConfig, pathStore = createConfigPathStore(), env = process.env, createSession = options => new PiBrokerSession(options) } = {}) {
   let owner = null, facade = null, ready = false, status = 'not_configured';
-  let generation = 0;
+  let generation = 0, operations = Promise.resolve();
+  const schedule = operation => {
+    const epoch = ++generation;
+    ready = false;
+    const next = operations.then(() => operation(epoch));
+    operations = next.catch(() => {});
+    return next;
+  };
   const notify = (ctx, text, kind = 'info') => { if (ctx?.hasUI) ctx.ui.notify(text, kind); };
   const setStatus = ctx => { if (ctx?.hasUI) ctx.ui.setStatus('psst', `Psst: ${status}`); };
   const stop = async () => {
-    generation++;
     const prior = owner; owner = null; facade = null; ready = false;
     if (prior) await prior.close();
   };
-  pi.on('session_start', async (_event, ctx) => {
+  const connect = async (ctx, epoch, selectedConfig) => {
     await stop();
-    const epoch = generation;
+    if (epoch !== generation) return;
     try {
-      const config = configReader();
+      const config = selectedConfig || configReader(env, env.PSST_CONFIG_FILE || env.PSST_CONFIG || pathStore.read());
       if (!config) { status = 'not_configured'; setStatus(ctx); return; }
       const hostSessionId = ctx.sessionManager.getSessionId();
       const current = createSession({ config, hostSessionId,
@@ -39,12 +46,26 @@ export function installExtension(pi, Type, { configReader = readConfig, createSe
       if (prior) await prior.close();
       setStatus(ctx); notify(ctx, `Psst could not connect (${status}). Check the private bundle and use /reload to retry.`, 'warning');
     }
+  };
+  pi.on('session_start', async (_event, ctx) => schedule(epoch => connect(ctx, epoch)));
+  pi.on('session_shutdown', async () => schedule(async () => { await stop(); status = 'stopped'; }));
+  pi.registerCommand('psst-connect', {
+    description: 'Connect this Pi session using an absolute connection.json path; remember only the path',
+    handler: async (args, ctx) => {
+      try {
+        const path = validateConfigPath(args.trim());
+        const config = configReader(env, path);
+        pathStore.write(path);
+        await schedule(epoch => connect(ctx, epoch, config));
+        if (env.PSST_CONFIG_FILE || env.PSST_CONFIG) notify(ctx, 'An existing PSST_CONFIG_FILE/PSST_CONFIG environment setting still takes precedence after /reload.', 'warning');
+        notify(ctx, ready ? 'Psst connected. Configuration path saved; no restart needed.' : 'Psst path saved. Check /psst-status; /reload retries the connection.');
+      } catch (error) { notify(ctx, `Psst could not save configuration (${safeError(error).error?.code || 'invalid_configuration'}). Use /psst-connect /absolute/path/connection.json.`, 'warning'); }
+    },
   });
-  pi.on('session_shutdown', async () => { await stop(); status = 'stopped'; });
   pi.registerCommand('psst-status', {
     description: 'Show this Pi session’s Psst broker status and client ID',
     handler: async (_args, ctx) => {
-      notify(ctx, ready && owner ? `Psst ${status}; client ID ${owner.inbox.identity.client_id}; inbox ${owner.inbox.stats().pending_count} pending. Cooperative mode: ask the agent to check broker_receive.` : `Psst ${status}. Set PSST_CONFIG_FILE to the private connection.json bundle, then /reload.`);
+      notify(ctx, ready && owner ? `Psst ${status}; client ID ${owner.inbox.identity.client_id}; inbox ${owner.inbox.stats().pending_count} pending. Cooperative mode: ask the agent to check broker_receive.` : `Psst ${status}. Use /psst-connect /absolute/path/connection.json. No restart required.`);
     },
   });
   const empty = Type.Object({}, { additionalProperties: false });