@hwip/cli 0.1.16 → 0.1.17

package/README.md

@@ -573,6 +573,17 @@ again picks up that run's conversation, not the newest one. If the name
 is live again by then, that run starts beside it under the next free name
 of the family (`<name>-2`, `<name>-3`, …) instead of being refused.
 
+The phone can also start a **new** session in a project this machine has
+run before: the same request with `fresh: true` starts the agent recorded
+for that session in its directory, with no conversation picked up, under
+the session's name or — when that runs — the next free name of its family.
+The directory and the agent still come only from this machine's record, so
+the phone cannot name either. The listener advertises `session-start-v1`
+so the apps offer it only to a build that knows it. Ending a session from
+the phone is `agent.session.exit.request`: `C-c`, the agent's own quit
+command, then `C-d` — never a forced kill, so an agent that will not quit is
+reported as still running.
+
 Two details worth knowing:
 
 - It fires at **user login**, not at boot. Without automatic login, the

package/dist/device-presence.d.ts

@@ -1,3 +1,9 @@
+/**
+ * This build reads `fresh` on a resume request (`listener.ts` `handleSessionResumeRequest`): the phone may start a new
+ * session in a recorded session's project. An older listener would resume the recorded conversation instead, so the apps
+ * offer it only to a computer that lists this.
+ */
+export declare const SESSION_START_CAPABILITY = "session-start-v1";
 /** The one message both halves of presence ride; the server answers
  *  `listener.presence.ack` or `listener.presence.error`. */
 export declare const LISTENER_PRESENCE = "listener.presence";

package/dist/device-presence.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createDeviceKeyRegistration = exports.LISTENER_PRESENCE = void 0;
+exports.createDeviceKeyRegistration = exports.LISTENER_PRESENCE = exports.SESSION_START_CAPABILITY = void 0;
 /**
  * Per-device E2E (ADR-0007) — put this machine's public key on its device
  * record, so other devices can wrap pushes and files for it.
@@ -28,13 +28,20 @@ exports.createDeviceKeyRegistration = exports.LISTENER_PRESENCE = void 0;
  * a file in chunks only for a device that lists `file-chunk-v1`, and one over
  * the relay's ceiling over LAN only to one that lists `lan-large-v1`; an app
  * offers `once` schedules and schedules into a session only to one that lists
- * `schedule-session-v1`. In one frame
+ * `schedule-session-v1`, and a new session in a project only to one that
+ * lists `session-start-v1`. In one frame
  * with the key, because a server from before `capabilities` answers a frame
  * that carries nothing else it knows with an error.
  */
 const file_crypto_js_1 = require("./file-crypto.js");
 const lan_receiver_js_1 = require("./lan-receiver.js");
 const schedule_js_1 = require("./schedule.js");
+/**
+ * This build reads `fresh` on a resume request (`listener.ts` `handleSessionResumeRequest`): the phone may start a new
+ * session in a recorded session's project. An older listener would resume the recorded conversation instead, so the apps
+ * offer it only to a computer that lists this.
+ */
+exports.SESSION_START_CAPABILITY = 'session-start-v1';
 /** The one message both halves of presence ride; the server answers
  *  `listener.presence.ack` or `listener.presence.error`. */
 exports.LISTENER_PRESENCE = 'listener.presence';
@@ -45,7 +52,7 @@ const createDeviceKeyRegistration = (deps) => {
     const register = async () => {
         try {
             const publicKey = await deps.publicKey();
-            const sent = deps.send({ type: exports.LISTENER_PRESENCE, data: { publicKey, capabilities: [file_crypto_js_1.FILE_CHUNK_CAPABILITY, lan_receiver_js_1.LAN_LARGE_CAPABILITY, schedule_js_1.SCHEDULE_SESSION_CAPABILITY] } });
+            const sent = deps.send({ type: exports.LISTENER_PRESENCE, data: { publicKey, capabilities: [file_crypto_js_1.FILE_CHUNK_CAPABILITY, lan_receiver_js_1.LAN_LARGE_CAPABILITY, schedule_js_1.SCHEDULE_SESSION_CAPABILITY, exports.SESSION_START_CAPABILITY] } });
             if (!sent)
                 deps.log('device key: not registered — no connection right now, retried at the next open');
             return sent;

package/dist/listener.d.ts

@@ -551,6 +551,12 @@ export interface SessionResumeRequest {
      * it reads as a run id.
      */
     runId?: string;
+    /**
+     * A new session in that session's project, not the session again (hwip docs/session-runs.md Q47): the recorded
+     * directory and agent, no conversation picked up, and beside the name when it runs. Read only when it is `true`.
+     * Advertised as `SESSION_START_CAPABILITY` (`device-presence.ts`) — an older listener would resume the recorded conversation instead.
+     */
+    fresh?: boolean;
     requestId?: string;
 }
 export interface SessionResumeResult {

package/dist/listener.js

@@ -369,6 +369,12 @@ const RATE_LIMIT_TOKENS = 120;
 const RATE_LIMIT_WINDOW_MS = 60_000;
 /** What one command submit costs, keeping its ceiling at the old 30/min. */
 const SUBMIT_COST = 4;
+/**
+ * What a fresh start costs on its family's own bucket (`start:<family base>`): three new agents a minute. Each one is a
+ * process left running, and every name of the family leads to the same bucket, so a session budget of 30 a minute
+ * cannot fill the family's 20 names in one burst.
+ */
+const FRESH_START_COST = RATE_LIMIT_TOKENS / 3;
 // Shells are refused: a shell prompt + send-keys = arbitrary command exec.
 const SHELL_COMMANDS = new Set(['bash', 'zsh', 'fish', 'sh', 'dash', 'ksh', 'tcsh', 'csh', 'pwsh']);
 // Auth-failure close codes: retrying with the same bad credentials hammers
@@ -1546,13 +1552,16 @@ const handleSessionResumeRequest = (req, send) => {
     // the family `hwip cc` would pick (Q41), counted from the family base so a
     // busy `<base>-2` leads to `<base>-3`. A request without a run id is an
     // older app that only knows the name, and still gets the refusal it renders.
+    // A fresh start asks for a new session, so a live name is no refusal either, and no conversation is picked up —
+    // the live one holding the recorded conversation included.
+    const fresh = req.fresh === true;
     const live = new Set((0, tmux_liveness_js_1.liveSessionNames)() ?? []);
     const target = !live.has(sessionName)
         ? sessionName
-        : runId !== undefined
+        : runId !== undefined || fresh
             ? (0, wrapper_js_1.familyNames)(familyBase(sessionName)).find((name) => !live.has(name))
             : undefined;
-    if (!target || conversationRunning(known, live))
+    if (!target || (!fresh && conversationRunning(known, live)))
         return reply({ error: 'already_running' });
     if (!(0, session_registry_js_1.sessionDirectoryExists)(known)) {
         (0, listener_log_js_1.log)(`✗ resume ${sessionName}: ${known.cwd} is gone`);
@@ -1563,6 +1572,11 @@ const handleSessionResumeRequest = (req, send) => {
         (0, listener_log_js_1.log)(`✗ resume ${sessionName}: no binary for agent kind ${known.agentKind}`);
         return reply({ error: 'unknown_agent' });
     }
+    // A fresh start leaves one more process running each time, so the family pays on a bucket of its own as well —
+    // charged only here, where it starts one: a refusal above says why, not that the budget ran out.
+    if (fresh && !(0, exports.checkRateLimit)(`start:${familyBase(sessionName)}`, undefined, FRESH_START_COST)) {
+        return reply({ error: 'rate_limited' });
+    }
     // argv, never a shell string: the binary comes from the agent table and the
     // directory from our own record, and neither is concatenated into anything
     // a shell would re-parse. A recorded label means the session carried
@@ -1572,7 +1586,7 @@ const handleSessionResumeRequest = (req, send) => {
     const sidecar = known.label && known.project
         ? [';', 'set-option', config_js_1.SESSION_PROJECT_OPTION, known.project, ';', 'set-option', config_js_1.SESSION_LABEL_OPTION, known.label]
         : [];
-    const conversation = resumableConversation(agent, known);
+    const conversation = fresh ? null : resumableConversation(agent, known);
     // tmux gives the new pane this client's PATH. A login service's PATH has none
     // of the agent directories, so they go on as schedule launches add them —
     // otherwise the agent is not found and the session ends as it starts.
@@ -1583,7 +1597,7 @@ const handleSessionResumeRequest = (req, send) => {
     }
     const resumedFrom = conversation ? ` (conversation ${conversation.id.slice(0, 8)})` : '';
     const beside = target === sessionName ? '' : ` as ${target}`;
-    (0, listener_log_js_1.log)(`⟲ resume ${sessionName}${beside}: ${agent.binary}${resumedFrom} in ${known.cwd}`);
+    (0, listener_log_js_1.log)(`${fresh ? '＋ start' : '⟲ resume'} ${sessionName}${beside}: ${agent.binary}${resumedFrom} in ${known.cwd}`);
     return reply({ resumed: true, sessionName: target });
 };
 exports.handleSessionResumeRequest = handleSessionResumeRequest;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hwip/cli",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "Hwip CLI + push notification SDK for AI agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",