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

package/README.md

@@ -33,24 +33,32 @@ This uses the default branch; wait for the scope correction to merge first. To t
 ### From npm (only after publication)
 
 ```sh
-pi install npm:@matuto-ai/pi-broker-connector@0.1.1
+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,7 +119,7 @@ Tests cover private bundle validation, exact session isolation, duplicate owners
 
 ## Publishing
 
-The `0.1.1` patch prepares the next trusted-publisher run without changing runtime behavior. After this version-bump PR is merged, the owner can create a GitHub release with tag **`v0.1.1`**. Preparing this PR does not publish that release or npm version.
+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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matuto-ai/pi-broker-connector",
-  "version": "0.1.1",
+  "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 });