@north-light/crouter 0.3.299 → 0.3.300

package/dist/commands/__tests__/node-message.test.js

@@ -1,14 +1,99 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { renderLeafArgv } from '../../core/help.js';
+import { PassThrough } from 'node:stream';
+import { parseArgv } from '../../core/command.js';
+import { renderBranch, renderLeafArgv } from '../../core/help.js';
 import { nodeMessage } from '../node/message.js';
+function messageLeaf(name) {
+    const leaf = nodeMessage.children.find((child) => child.kind === 'leaf' && child.name === name);
+    if (leaf === undefined || leaf.kind !== 'leaf')
+        assert.fail(`node message ${name} leaf is missing`);
+    return leaf;
+}
+async function withFakeStdin(fake, fn) {
+    const real = process.stdin;
+    Object.defineProperty(process, 'stdin', { value: fake, configurable: true });
+    try {
+        return await fn();
+    }
+    finally {
+        Object.defineProperty(process, 'stdin', { value: real, configurable: true });
+    }
+}
+function pipedStdin(body) {
+    const stdin = new PassThrough();
+    stdin.end(body);
+    return stdin;
+}
+test('node message help names the target flag in the family and both child rubrics', () => {
+    const rendered = renderBranch(nodeMessage.help);
+    assert.match(rendered, /targeted with `--to <node-id>` or `--self`/);
+    assert.match(rendered, /send[\s\S]*?whenToUse="a target chosen with `--to <node-id>` or `--self` should have information/);
+    assert.match(rendered, /request[\s\S]*?whenToUse="a target chosen with `--to <node-id>` or `--self` must hand back one answer/);
+});
 test('node message send help documents the reopen re-task semantics', () => {
-    const send = nodeMessage.children.find((child) => child.kind === 'leaf' && child.name === 'send');
-    if (send === undefined || send.kind !== 'leaf')
-        assert.fail('node message send leaf is missing');
-    const rendered = renderLeafArgv(send.help);
+    const rendered = renderLeafArgv(messageLeaf('send').help);
     assert.match(rendered, /--reopen/);
     assert.match(rendered, /Re-task the target: commits it resident and clears any finalization latch before delivery/);
     assert.match(rendered, /valid for live, parked, and finalized targets/);
     assert.match(rendered, /Without it, a finalized target rejects delivery before an inbox entry is appended or a revive is attempted/);
 });
+test('node message send explains a positional node id without a target flag', async () => {
+    const send = messageLeaf('send');
+    const nodeId = '3zl47w7d-mtqb57ts-74ea25fe';
+    await assert.rejects(() => send.run({ body: nodeId }), (error) => {
+        assert.equal(error.code, 'bad_target');
+        assert.equal(error.message, 'no target given — the message body is not a node id');
+        assert.equal(error.details?.field, 'to');
+        assert.equal(error.details?.next, 'Pass the node id with --to <node-id> and provide the message body as a positional argument or on stdin, or use --self.');
+        return true;
+    });
+    const params = send.help.params;
+    if (params === undefined)
+        assert.fail('node message send input schema is missing');
+    await withFakeStdin(pipedStdin('A long message body.'), () => assert.rejects(() => parseArgv(params, [nodeId]), (error) => {
+        assert.equal(error.code, 'bad_invocation');
+        assert.equal(error.message, 'no target given — the positional argument is the message body, not a node id');
+        assert.equal(error.details?.field, 'to');
+        assert.equal(error.details?.next, 'Pass the node id with --to <node-id> and pipe the message body on stdin, or use --self.');
+        return true;
+    }));
+});
+test('node message request gives the same no-target guidance', async () => {
+    const request = messageLeaf('request');
+    const nodeId = '3zl47w7d-mtqb57ts-74ea25fe';
+    await assert.rejects(() => request.run({ body: nodeId, outputSchema: '{}' }), (error) => {
+        assert.equal(error.code, 'bad_target');
+        assert.equal(error.message, 'no target given — the message body is not a node id');
+        assert.equal(error.details?.field, 'to');
+        assert.equal(error.details?.next, 'Pass the node id with --to <node-id> and provide the message body as a positional argument or on stdin, or use --self.');
+        return true;
+    });
+    const params = request.help.params;
+    if (params === undefined)
+        assert.fail('node message request input schema is missing');
+    await withFakeStdin(pipedStdin('A long message body.'), () => assert.rejects(() => parseArgv(params, [nodeId]), (error) => {
+        assert.equal(error.code, 'bad_invocation');
+        assert.equal(error.message, 'no target given — the positional argument is the message body, not a node id');
+        assert.equal(error.details?.field, 'to');
+        assert.equal(error.details?.next, 'Pass the node id with --to <node-id> and pipe the message body on stdin, or use --self.');
+        return true;
+    }));
+});
+test('a targeted node message keeps positional-body parsing and generic stdin conflicts', async () => {
+    const send = messageLeaf('send');
+    const params = send.help.params;
+    if (params === undefined)
+        assert.fail('node message send input schema is missing');
+    const parsed = await withFakeStdin(pipedStdin(''), () => parseArgv(params, ['message body', '--to', 'target-node']));
+    assert.equal(parsed['body'], 'message body');
+    assert.equal(parsed['to'], 'target-node');
+    const genericParams = [{ kind: 'stdin', name: 'body', required: false, constraint: 'body' }];
+    await withFakeStdin(pipedStdin('A long message body.'), () => assert.rejects(() => parseArgv(genericParams, ['message body']), (error) => {
+        assert.equal(error.code, 'bad_invocation');
+        assert.equal(error.message, 'both a positional argument ("message body") and piped stdin were provided for body');
+        assert.equal(error.details?.field, 'body');
+        assert.equal(error.details?.next, 'Pass exactly one: either the positional argument or piped stdin, not both.');
+        return true;
+    }));
+});

package/dist/commands/node/message.js

@@ -11,15 +11,16 @@ function requireNonBlankDiscriminant(input, name) {
         throw new InputError({ error: 'empty_discriminant', message: `--${flag} must contain non-whitespace text`, received: typeof value === 'string' ? value : String(value), field: flag, next: `Pass a non-empty --${flag} value, or omit the flag.` });
     }
 }
-async function resolveMsgTarget(input) {
+async function resolveMsgTarget(input, hasBody) {
     const to = input['to']?.trim();
     const self = input['self'] === true;
     const hasTo = to !== undefined && to !== '';
     if (hasTo === self) {
         throw new InputError({
             error: 'bad_target',
-            message: hasTo && self ? '--to and --self are mutually exclusive' : 'exactly one of --to or --self is required',
-            next: 'Pass --to <node-id> or --self.',
+            message: hasTo && self ? '--to and --self are mutually exclusive' : hasBody ? 'no target given — the message body is not a node id' : 'exactly one of --to or --self is required',
+            field: hasTo ? undefined : 'to',
+            next: hasTo ? 'Pass --to <node-id> or --self.' : hasBody ? 'Pass the node id with --to <node-id> and provide the message body as a positional argument or on stdin, or use --self.' : 'Pass --to <node-id> or --self.',
         });
     }
     if (self) {
@@ -41,9 +42,19 @@ function messageOutput() {
         { name: 'guidance', type: 'string', required: true, constraint: 'Immediate action confirmation.' },
     ];
 }
+function missingMessageTargetForBody(input) {
+    const to = input['to']?.trim();
+    if ((to !== undefined && to !== '') || input['self'] === true)
+        return undefined;
+    return {
+        message: 'no target given — the positional argument is the message body, not a node id',
+        field: 'to',
+        next: 'Pass the node id with --to <node-id> and pipe the message body on stdin, or use --self.',
+    };
+}
 function messageSendParams() {
     return [
-        { kind: 'stdin', name: 'body', required: false, constraint: 'Visible message body. Required unless --situational-context is supplied.' },
+        { kind: 'stdin', name: 'body', required: false, constraint: 'Visible message body. Required unless --situational-context is supplied.', positionalStdinConflict: missingMessageTargetForBody },
         { kind: 'flag', name: 'to', type: 'string', required: false, constraint: 'Target an existing node by id. Exactly one of --to or --self is required.' },
         { kind: 'flag', name: 'self', type: 'bool', required: false, constraint: 'Target the calling node. Exactly one of --to or --self is required.' },
         { kind: 'flag', name: 'tier', type: 'enum', choices: ['critical', 'urgent', 'normal', 'deferred'], required: false, default: 'normal', constraint: 'Delivery urgency. Deferred never wakes an idle node, except a terminal one, which has no later cycle to read it on and is raised to urgent.' },
@@ -53,7 +64,7 @@ function messageSendParams() {
 }
 function messageRequestParams() {
     return [
-        { kind: 'stdin', name: 'body', required: false, constraint: 'Visible message body. The schema alone is a complete request.' },
+        { kind: 'stdin', name: 'body', required: false, constraint: 'Visible message body. The schema alone is a complete request.', positionalStdinConflict: missingMessageTargetForBody },
         { kind: 'flag', name: 'to', type: 'string', required: false, constraint: 'Target an existing node by id. Exactly one of --to or --self is required.' },
         { kind: 'flag', name: 'self', type: 'bool', required: false, constraint: 'Target the calling node. Exactly one of --to or --self is required.' },
         { kind: 'flag', name: 'tier', type: 'enum', choices: ['critical', 'urgent', 'normal'], required: false, default: 'normal', constraint: 'Delivery urgency. Every accepted tier may revive a dormant target, because the request must be answered; deferred is rejected for that reason.' },
@@ -68,10 +79,10 @@ async function runMessageEngine(input) {
     if (situationalContextSupplied && situationalContextRaw === '') {
         throw new InputError({ error: 'empty_situational_context', message: '--situational-context must contain non-whitespace text', field: 'situational-context', next: 'Pass non-whitespace text, or omit --situational-context.' });
     }
-    const { targetId } = await resolveMsgTarget(input);
     const bodyRaw = input['body'];
     const body = bodyRaw !== undefined ? bodyRaw.trim() : undefined;
     const hasBody = body !== undefined && body !== '';
+    const { targetId } = await resolveMsgTarget(input, hasBody);
     const tierRaw = input['tier'];
     const hasTier = tierRaw !== undefined && tierRaw !== '';
     const outputSchemaParsed = parseOutputSchemaValue(input['outputSchema']);
@@ -107,7 +118,7 @@ async function runMessageEngine(input) {
 const nodeMessageSend = defineLeaf({
     name: 'send',
     description: 'deliver an inbox message to an existing node immediately',
-    whenToUse: 'a node that already exists should have information or new direction now — steering a worker mid-task, handing over a finding it needs, correcting a wrong turn, or waking a dormant node with fresh work. The target reads it and decides what to do with it. Use `node message request` instead when you need an answer back in a shape you specify, and `node subscription add` when the target should keep receiving this node’s pushes rather than this one delivery',
+    whenToUse: 'a target chosen with `--to <node-id>` or `--self` should have information or new direction now — steering a worker mid-task, handing over a finding it needs, correcting a wrong turn, or waking a dormant node with fresh work. The target reads it and decides what to do with it. Use `node message request` instead when you need an answer back in a shape you specify, and `node subscription add` when the target should keep receiving this node’s pushes rather than this one delivery',
     help: {
         name: 'node message send',
         summary: 'deliver an inbox message to an existing node immediately',
@@ -122,7 +133,7 @@ const nodeMessageSend = defineLeaf({
 const nodeMessageRequest = defineLeaf({
     name: 'request',
     description: 'deliver an immediate typed-output request to an existing node',
-    whenToUse: 'a node that already exists must hand back one answer in a shape you fix — a choice among options, a structured extraction, a verdict your own logic will branch on — or must be held to answering at all before it goes quiet. Use `node message send` instead when prose in the target’s own judgment is enough, and `node new --output-schema` when no node holds the context yet and the work needs a fresh agent',
+    whenToUse: 'a target chosen with `--to <node-id>` or `--self` must hand back one answer in a shape you fix — a choice among options, a structured extraction, a verdict your own logic will branch on — or must be held to answering at all before it goes quiet. Use `node message send` instead when prose in the target’s own judgment is enough, and `node new --output-schema` when no node holds the context yet and the work needs a fresh agent',
     help: {
         name: 'node message request',
         summary: 'deliver an immediate typed-output request to an existing node',
@@ -144,7 +155,7 @@ export const nodeMessage = defineBranch({
     help: {
         name: 'node message',
         summary: 'deliver one immediate inbox entry to an existing node',
-        model: 'Both children append one inbox entry to a node that already exists, targeted by id or --self, and may revive it if it is dormant. They differ in what the delivery obligates. An ordinary message obligates nothing: the target reads it and acts however it judges best. A request installs a one-off output schema and holds the target awake and owing until it answers; the answer is validated against the schema, written to the target’s result file, and pushed as an update report to the TARGET’S subscribers, so subscribe to it first if the answer has to reach you. Neither child creates that standing relationship — a durable delivery edge is `node subscription`, and work that needs a fresh agent is `node new`.',
+        model: 'Both children append one inbox entry to a node that already exists, targeted with `--to <node-id>` or `--self`, and may revive it if it is dormant. They differ in what the delivery obligates. An ordinary message obligates nothing: the target reads it and acts however it judges best. A request installs a one-off output schema and holds the target awake and owing until it answers; the answer is validated against the schema, written to the target’s result file, and pushed as an update report to the TARGET’S subscribers, so subscribe to it first if the answer has to reach you. Neither child creates that standing relationship — a durable delivery edge is `node subscription`, and work that needs a fresh agent is `node new`.',
     },
     children: [nodeMessageSend, nodeMessageRequest],
 });

package/dist/core/command.js

@@ -503,7 +503,8 @@ export async function parseArgv(params, tokens, options) {
                 // whole invocation waiting for a close that will never come.
                 const piped = await peekStdinRaw();
                 if (piped.trim() !== '') {
-                    throw parseArgvError('bad_invocation', `both a positional argument ("${positionalValue}") and piped stdin were provided for ${stdinParam.name}`, positionalValue, stdinParam.name, `Pass exactly one: either the positional argument or piped stdin, not both.`);
+                    const conflict = stdinParam.positionalStdinConflict?.(result);
+                    throw parseArgvError('bad_invocation', conflict?.message ?? `both a positional argument ("${positionalValue}") and piped stdin were provided for ${stdinParam.name}`, positionalValue, conflict?.field ?? stdinParam.name, conflict?.next ?? `Pass exactly one: either the positional argument or piped stdin, not both.`);
                 }
                 result[flagNameToKey(stdinParam.name)] = positionalValue;
                 stdinWasSupplied = true; // positional supplying stdin counts as supplied

package/dist/core/help.d.ts

@@ -87,6 +87,13 @@ export interface StdinParam {
     /** Whether one positional token may supply stdin instead of a pipe. Defaults
      * to true for existing stdin-body leaves; false requires actual stdin. */
     allowPositional?: boolean;
+    /** Optional leaf-specific recovery when a positional stdin body collides with
+     * piped stdin. Return undefined to keep the generic collision error. */
+    positionalStdinConflict?: (input: Readonly<Record<string, unknown>>) => {
+        message: string;
+        field?: string;
+        next: string;
+    } | undefined;
 }
 /** --context-file PATH: reads and JSON-parses the file at PATH. */
 export interface ContextFileParam {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.299",
+  "version": "0.3.300",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.299",
+  "version": "0.3.300",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.299",
+      "version": "0.3.300",
       "hasInstallScript": true,
       "license": "MIT",
       "workspaces": [
@@ -5206,17 +5206,17 @@
     },
     "packages/crouter-api": {
       "name": "@north-light/crouter-api",
-      "version": "0.3.299",
+      "version": "0.3.300",
       "license": "UNLICENSED"
     },
     "packages/crouter-env-docker": {
       "name": "@north-light/crouter-env-docker",
-      "version": "0.3.299",
+      "version": "0.3.300",
       "license": "UNLICENSED"
     },
     "packages/crouter-sdk": {
       "name": "@north-light/crouter-sdk",
-      "version": "0.3.299",
+      "version": "0.3.300",
       "license": "UNLICENSED",
       "dependencies": {
         "@north-light/crouter-api": "^0.3.295"