@knowttl/artium-axi 0.0.0 → 0.0.3

package/README.md

@@ -20,7 +20,7 @@ See the [evidence ledger](docs/evidence-ledger.md) for the acceptance boundaries
 ## Agent Ergonomics
 
 - Running without arguments shows identity, roles, available tools, cached health and pinned versions.
-- Tool lists use a compact `name`, `status`, `version` schema and suggest a detail view and first call.
+- Tool lists show cached health, pinned versions and write-access status and suggest a detail view and first call.
 - Empty lists explain why no enabled tool is available and direct you to an administrator.
 - Local help works before sign-in and includes usage, purpose, flags and an example.
 - Artium errors use TOON on stdout; upstream calls preserve separate stdout, stderr and exit status.
@@ -369,6 +369,7 @@ After signing in, run `node dist/cli/artium-axi.mjs setup --host codex` to insta
 The root package remains private for server development; `pnpm build:npm` stages the separate public client package in `dist/npm` using the root package version.
 Run `npm pack --dry-run ./dist/npm` to inspect the client tarball before release.
 Only the bundled CLI, skill, README, LICENSE, NOTICE and client package metadata are included.
+See [npm client releases](docs/runbook.md#npm-client-releases) for automated publishing and owner setup.
 
 ## Usage
 
@@ -377,6 +378,7 @@ Only the bundled CLI, skill, README, LICENSE, NOTICE and client package metadata
 | Command | Purpose |
 | --- | --- |
 | `artium-axi` | Show identity, roles and available tools. |
+| `artium-axi --version` | Print only the client package version and a newline, then exit without configuration, sign-in or network access. |
 | `artium-axi login --username synthetic-user` | Sign in with a local account. |
 | `artium-axi login --sso` | Sign in through browser approval with an enabled SSO provider; works on headless and SSH hosts. |
 | `artium-axi passwd` | Change your password, then sign in again. |
@@ -411,9 +413,8 @@ Other Azure commands, including the dashboard and `home`, leave stdin unread; he
 Local upload paths become leaf names in the request; duplicate leaf names and oversized input are refused.
 The API supports bounded stdin and named uploads through the [shared API contract](src/shared/api.ts).
 
-Write permission remains subject to the pinned tool's native gates and the configured adapter policy.
-Vectra writes require its configured allowlist and upstream confirmation; Artium does not add a universal confirmation flag.
-Falcon has no editable native write settings.
+See [write-access administration](docs/runbook.md#roles-credentials-and-health) for per-tool switches, native write gates and the current Falcon limitation.
+Artium does not add a universal confirmation flag.
 
 Azure writes whose outcome is unknown are not retried and return `UNKNOWN_OUTCOME` with state-check guidance; reads may still retry.
 Artium also returns this error when its runner times out, cancels or receives a process signal after starting an executed Azure write; read timeouts remain `TIMEOUT`.
@@ -659,11 +660,12 @@ See the [API contract](src/shared/api.ts) and [retention and export runbook](doc
 
 Use `login --password-stdin` or `passwd --password-stdin` to supply the login or new password through stdin.
 Stdin removes one final LF or CRLF and preserves all other spaces and Unicode.
-Password arguments are refused; tokens are never printed.
+Password arguments are refused; tokens are never printed to stdout or stderr.
 Ordinary password changes also require the current password through the terminal prompt or `ARTIUM_AXI_CURRENT_PASSWORD`.
 Clear password environment values after use.
 
-Sessions live in `artium-axi/session.json` under the applicable base directory and are bound to the normalized server URL.
+By default, sessions live in `artium-axi/session.json` under the applicable base directory and are bound to the normalized server URL.
+Callers that manage their own tokens can instead use [externally managed client sessions](#externally-managed-client-sessions).
 POSIX directories use mode 0700 and files mode 0600; Windows uses a restricted ACL and refuses storage if it cannot establish it.
 Do not export or share the session file.
 CLI processes serialize refreshes through `session.lock`; after `SESSION_BUSY`, remove that lock directory only when every CLI process has exited.
@@ -674,6 +676,46 @@ Certificate verification remains enforced even with `NODE_TLS_REJECT_UNAUTHORIZE
 Only an explicit pre-execution `TOKEN_EXPIRED` response permits one serialized refresh and retry.
 A network failure or uncertain command outcome is never retried automatically.
 
+### Externally managed client sessions
+
+Callers that keep credentials outside the CLI can opt in with one leading flag: `artium-axi --managed-session <command> <args>`.
+The caller supplies inherited pipes or sockets: fd 3 for session input and fd 4 for private rotation output.
+Stdin remains available for tool input; stdout and stderr retain their normal command formats.
+Do not pass tokens in arguments or environment variables, connect fd 4 to a log or public output, or redirect either private channel to a disk file.
+The CLI refuses regular files as private channels and never reads, creates, locks, updates or deletes `session.json` in this mode.
+
+Send one UTF-8 JSON object of at most 64 KiB to fd 3, then close the input pipe:
+
+```json
+{"serverUrl":"https://artium.example.test","accessToken":"CANARY-access","refreshToken":"CANARY-refresh"}
+```
+
+`serverUrl` must match the normalized `ARTIUM_AXI_URL`, allowing a final slash.
+`accessToken` is required and nonempty; `refreshToken` is optional and nonempty when supplied.
+The optional fields `status: "authenticated"`, `accessExpiresAt` and `familyExpiresAt` (integer Unix milliseconds) allow a rotation record to be reused as input; other fields are refused.
+The caller owns token acquisition, expiry policy, refresh serialization across processes and secure persistence.
+Managed mode supports the home view, `whoami`, `tools`, `tools show`, `doctor` and tool commands.
+`login`, `passwd`, `logout` and `setup` are refused before any network call; ordinary sign-in and its server-version warning remain unchanged without the flag.
+Help is available without private channels through `artium-axi --help`.
+
+Only an explicit `TOKEN_EXPIRED` response permits a single refresh and retry of that request.
+Without a refresh token, or if refresh is refused, the CLI returns the authentication error for the caller to handle.
+Network failures and uncertain outcomes are never automatically retried.
+After a successful refresh, fd 4 receives one newline-terminated JSON object before the request is retried:
+
+```json
+{"serverUrl":"https://artium.example.test","status":"authenticated","accessToken":"CANARY-new-access","refreshToken":"CANARY-new-refresh","accessExpiresAt":1800000000000,"familyExpiresAt":1800003600000}
+```
+
+Every rotation is delivered even if the subsequent request fails; an invocation without rotation writes no record.
+Consume fd 4 concurrently with stdout and stderr, and retain rotations regardless of the command's exit status.
+If rotation delivery fails, the CLI refuses to retry the request and returns `INVALID_INPUT` (exit 2); the caller must recover the session rather than reuse the consumed refresh token.
+Managed public output is buffered and scanned against supplied and rotated tokens and their canonical encodings before printing; a match withholds both streams and returns `SECRET_IN_OUTPUT`.
+
+Exit codes are 0 for success, 2 for invalid input, client configuration or private channels and refused commands, and 1 for authentication, server-binding, transport or output-scanning failures.
+Tool exit codes pass through as usual.
+Missing or closed descriptors, invalid JSON and mismatched server bindings fail before network access; no failure falls back to a session file.
+
 ### Server settings and custody
 
 | Variable | Meaning |

package/bin/artium-axi.mjs

@@ -4498,9 +4498,9 @@ var $ZodTransform = /* @__PURE__ */ $constructor("$ZodTransform", (inst, def) =>
     }
     const _out = def.transform(payload.value, payload);
     if (ctx.async) {
-      const output2 = _out instanceof Promise ? _out : Promise.resolve(_out);
-      return output2.then((output3) => {
-        payload.value = output3;
+      const output3 = _out instanceof Promise ? _out : Promise.resolve(_out);
+      return output3.then((output4) => {
+        payload.value = output4;
         return payload;
       });
     }
@@ -4950,12 +4950,12 @@ var $ZodFunction = /* @__PURE__ */ $constructor("$ZodFunction", (inst, def) => {
       output: inst._def.output
     });
   };
-  inst.output = (output2) => {
+  inst.output = (output3) => {
     const F = inst.constructor;
     return new F({
       type: "function",
       input: inst._def.input,
-      output: output2
+      output: output3
     });
   };
   return inst;
@@ -18364,14 +18364,14 @@ var ZodTransform = /* @__PURE__ */ $constructor("ZodTransform", (inst, def) => {
         payload.issues.push(util_exports.issue(_issue));
       }
     };
-    const output2 = def.transform(payload.value, payload);
-    if (output2 instanceof Promise) {
-      return output2.then((output3) => {
-        payload.value = output3;
+    const output3 = def.transform(payload.value, payload);
+    if (output3 instanceof Promise) {
+      return output3.then((output4) => {
+        payload.value = output4;
         return payload;
       });
     }
-    payload.value = output2;
+    payload.value = output3;
     return payload;
   };
 });
@@ -20048,7 +20048,7 @@ var nativeSettingsSchemas = {
     allowWrites: external_exports.boolean(),
     operations: external_exports.array(external_exports.string().min(1).max(256)).min(1).max(64)
   }).optional() }),
-  "falcon-axi": external_exports.strictObject({}),
+  "falcon-axi": external_exports.strictObject({ allowWrites: external_exports.boolean().optional() }),
   "vectra-axi": external_exports.strictObject({ writes: external_exports.strictObject({
     allowWrites: external_exports.boolean(),
     operations: external_exports.array(external_exports.string().min(1).refine((value) => value.trim().length > 0)).min(1)
@@ -20063,6 +20063,7 @@ var nativeSettingsSchemas = {
 };
 var healthSchema = external_exports.strictObject({
   status: external_exports.enum(["unconfigured", "unknown", "ok", "error", "disabled"]),
+  readOnly: external_exports.boolean().default(true),
   checkedAt: external_exports.number().int().nullable(),
   credentialRevision: external_exports.number().int().nullable(),
   errorCode: external_exports.enum(Object.keys(errors)).nullable()
@@ -20071,6 +20072,7 @@ var adminToolSchema = external_exports.strictObject({
   name: toolSchema,
   enabled: external_exports.boolean(),
   version: external_exports.string(),
+  readOnly: external_exports.boolean().default(true),
   nativeSettings: external_exports.record(external_exports.string(), external_exports.unknown()),
   revision: external_exports.number().int().positive(),
   updatedAt: external_exports.number().int().nullable(),
@@ -20394,6 +20396,7 @@ var toolsResponseSchema = external_exports.strictObject({
   tools: external_exports.array(external_exports.strictObject({
     name: toolSchema,
     version: external_exports.string(),
+    readOnly: external_exports.boolean().default(true),
     status: external_exports.enum(["unconfigured", "unknown", "ok", "error", "disabled"])
   }))
 });
@@ -20449,7 +20452,7 @@ import { rootCertificates } from "node:tls";
 // package.json
 var package_default = {
   name: "artium-axi",
-  version: "0.0.0",
+  version: "0.0.3",
   private: true,
   license: "MIT",
   type: "module",
@@ -20633,20 +20636,27 @@ var SessionStore = class {
 // src/cli/http.ts
 var DEFAULT_REQUEST_DEADLINE_MS = 9e4;
 var Client = class {
-  constructor(environment = process.env) {
+  constructor(environment = process.env, managed2) {
     this.environment = environment;
+    this.managed = managed2;
     try {
       const url2 = new URL(environment.ARTIUM_AXI_URL);
       if (url2.username || url2.password || url2.href.includes("?") || url2.href.includes("#") || url2.protocol !== "https:" && !(url2.protocol === "http:" && environment.ARTIUM_AXI_TEST_HTTP === "1" && ["localhost", "127.0.0.1", "[::1]"].includes(url2.hostname))) throw new Error();
       this.serverUrl = url2.href.replace(/\/$/, "");
-      this.sessions = new SessionStore(this.serverUrl, sessionPath(process.platform, environment));
+      if (!managed2) this.storedSessions = new SessionStore(this.serverUrl, sessionPath(process.platform, environment));
     } catch {
       throw new ArtiumError("CLIENT_CONFIG_INVALID");
     }
+    managed2?.checkServer(this.serverUrl);
   }
   environment;
+  managed;
   serverUrl;
-  sessions;
+  storedSessions;
+  get sessions() {
+    if (!this.storedSessions) throw new ArtiumError("INVALID_INPUT", "Session-file operations are unavailable in managed mode.");
+    return this.storedSessions;
+  }
   certificateVerified = false;
   async request(path, method, input2, token) {
     this.certificateVerified = false;
@@ -20722,6 +20732,10 @@ var Client = class {
     return result.body;
   }
   async authenticated(path, method, input2, previous) {
+    if (this.managed) return this.managed.authenticated(
+      (token) => this.request(path, method, input2, token),
+      (refreshToken) => this.request("/v1/auth/refresh", "POST", { refreshToken })
+    );
     const session = previous ? this.reload(previous) : this.sessions.read();
     if (!session) throw new ArtiumError("TOKEN_INVALID", void 0, "Run artium-axi login --username <username> --password-stdin.");
     if (session.status === "password-change-required") throw new ArtiumError("PASSWORD_CHANGE_REQUIRED");
@@ -20805,16 +20819,18 @@ async function readPassword(stdin, environmentVariable) {
 }
 
 // src/cli/doctor.ts
-async function doctor() {
+async function doctor(createClient = () => new Client(), write = (text2) => {
+  process.stdout.write(text2);
+}) {
   let failure2;
   const line = (name, pass, detail, error62) => {
     if (!pass) failure2 ??= error62 ?? new ArtiumError("INVALID_RESPONSE");
-    process.stdout.write(`${pass ? "pass" : "fail"}: ${name}${detail ? ` (${detail})` : ""}
+    write(`${pass ? "pass" : "fail"}: ${name}${detail ? ` (${detail})` : ""}
 `);
   };
   let client;
   try {
-    client = new Client();
+    client = createClient();
   } catch (error62) {
     for (const name of ["server address", "certificate", "token", "CLI version"]) line(name, false, "CLIENT_CONFIG_INVALID");
     throw error62;
@@ -22830,7 +22846,7 @@ var ldap_axi_default = {
 
 // src/cli/help.ts
 var commands = {
-  home: { usage: "artium-axi [tools [show <tool>]|whoami|login|passwd|logout|doctor|setup|<tool> <args>]", purpose: "Show your identity, roles and available tools.", flags: [], example: "artium-axi" },
+  home: { usage: "artium-axi [tools [show <tool>]|whoami|login|passwd|logout|doctor|setup|<tool> <args>]", purpose: "Show your identity, roles and available tools.", flags: ["--version (default false; print the client package version and exit)"], example: "artium-axi" },
   setup: {
     usage: "artium-axi setup --host <claude|codex|opencode|pi> [--hook] [--force]",
     purpose: "Install skills for your signed-in account\u2019s granted tools and an optional Claude Code session hook.",
@@ -22875,7 +22891,13 @@ var commands = {
 };
 function commandHelp(command) {
   const entry = commands[command];
-  const flags = [command === "falcon-axi" || command === "vectra-axi" || command === "ldap-axi" ? "--help before the tool name (default false)" : "--help (default false)", ...entry.flags];
+  const flags = [
+    command === "falcon-axi" || command === "vectra-axi" || command === "ldap-axi" ? "--help before the tool name (default false)" : "--help (default false)",
+    ...entry.flags,
+    "--managed-session before the command (default false; authenticated calls only; session JSON on inherited pipe fd 3, rotations as JSON lines on private pipe fd 4; no session file)",
+    "Managed input: {serverUrl, accessToken, refreshToken?}; close fd 3 after JSON (64 KiB maximum). Output: {serverUrl, status, accessToken, refreshToken, accessExpiresAt, familyExpiresAt} per rotation, before retry, including on later failure.",
+    "Managed exits: 0 success; 2 invalid JSON/descriptors or refused login/passwd/logout/setup; 1 authentication/transport failure; tool exit codes pass through. Only TOKEN_EXPIRED permits one refresh/retry; without refreshToken or on refusal, return control to the caller."
+  ];
   return `usage: ${entry.usage}
 purpose: ${entry.purpose}
 flags[${flags.length}]:
@@ -33710,25 +33732,25 @@ function rewriteDiscoveryHelp(help, tool) {
     examples: help.examples.map((example) => hostedHelp(example, tool, flags, true))
   });
 }
-function rewriteSuggestions(output2, tool, truncated = false) {
-  if (truncated) return output2;
+function rewriteSuggestions(output3, tool, truncated = false) {
+  if (truncated) return output3;
   const flags = managedFlags[tool];
-  if (!flags) return output2;
+  if (!flags) return output3;
   const executable = new RegExp(`^(?:artium-axi |npx -y @knowttl/)?${tool}(?=\\s|$)`);
-  if (executable.test(output2.replace(/^[ \t]*(?:(?:Command|Native operation|Examples): )?/, "")) || tool === "ldap-axi" && ldapHelp.test(output2)) return hostedHelp(output2, tool, flags, true);
+  if (executable.test(output3.replace(/^[ \t]*(?:(?:Command|Native operation|Examples): )?/, "")) || tool === "ldap-axi" && ldapHelp.test(output3)) return hostedHelp(output3, tool, flags, true);
   let spans;
   let unknownOutcome = false;
   try {
-    const json2 = output2.trimStart().startsWith("{");
-    let parsed = json2 ? jsonHelp(output2) : toonHelp(output2);
+    const json2 = output3.trimStart().startsWith("{");
+    let parsed = json2 ? jsonHelp(output3) : toonHelp(output3);
     if (tool === "ldap-axi" && parsed.document.description === "Read Active Directory and LDAPv3 directories safely with ldap-axi (read-only)" && Array.isArray(parsed.document.commands) && parsed.spans.length) {
       const home = {
         ...parsed.document,
         commands: parsed.document.commands.filter((command) => ldapCommands.includes(command)),
         help: [...parsed.spans.map((span) => span.value).filter((value) => !/^(?:Authentication auto selects|Set LDAP_AXI_URL)/.test(value) && value !== ldapCredentialGuidance), ldapCredentialGuidance]
       };
-      output2 = (json2 ? JSON.stringify(home) : encode3(home)) + "\n";
-      parsed = json2 ? jsonHelp(output2) : toonHelp(output2);
+      output3 = (json2 ? JSON.stringify(home) : encode3(home)) + "\n";
+      parsed = json2 ? jsonHelp(output3) : toonHelp(output3);
     }
     const { spans: suggestions, document } = parsed;
     spans = suggestions;
@@ -33736,15 +33758,15 @@ function rewriteSuggestions(output2, tool, truncated = false) {
       unknownOutcome = document?.code === "UNKNOWN_OUTCOME" || document?.error?.code === "UNKNOWN_OUTCOME";
     }
   } catch {
-    return output2;
+    return output3;
   }
   for (const span of [...spans].reverse()) {
     const value = hostedHelp(span.value, tool, flags, /^[ \t]*(?:Command|Native operation|Examples):/m.test(span.value));
     if (value === span.value) continue;
-    output2 = output2.slice(0, span.start) + (span.quoted || tool === "ldap-axi" && /[,\r\n]/.test(value) ? JSON.stringify(value) : value) + output2.slice(span.start + span.raw.length);
+    output3 = output3.slice(0, span.start) + (span.quoted || tool === "ldap-axi" && /[,\r\n]/.test(value) ? JSON.stringify(value) : value) + output3.slice(span.start + span.raw.length);
   }
-  spans = (output2.trimStart().startsWith("{") ? jsonHelp(output2) : toonHelp(output2)).spans;
-  if (spans.some((span) => /\\[`'"]/.test(span.value))) return output2;
+  spans = (output3.trimStart().startsWith("{") ? jsonHelp(output3) : toonHelp(output3)).spans;
+  if (spans.some((span) => /\\[`'"]/.test(span.value))) return output3;
   const insertions = /* @__PURE__ */ new Map();
   const removals = /* @__PURE__ */ new Map();
   for (const span of spans) {
@@ -33778,28 +33800,28 @@ function rewriteSuggestions(output2, tool, truncated = false) {
       if (!quote2 && /^(?:artium-axi |npx -y @knowttl\/)?\S+-axi(?:\s|$)/.test(command)) commandRanges.push([match.index, match.index + match[0].length]);
       const wrapped = command.startsWith(`artium-axi ${tool}`);
       if (!executable.test(quote2 ? command.split(quote2)[0] : command)) continue;
-      if (quote2 && !command.includes(quote2)) return output2;
+      if (quote2 && !command.includes(quote2)) return output3;
       const start = match.index + match[0].length - command.length;
       commandRanges.push([match.index, quote2 ? start + command.indexOf(quote2) + 1 : match.index + match[0].length]);
       commandEdit2(start, quote2 ? start + command.indexOf(quote2) : start + command.length, wrapped);
     }
     for (const match of span.value.matchAll(/(?<![^\s(])([`'"])([^\n]*?)(\1|(?=\n|$))/g)) {
       if (commandRanges.some(([start, end]) => match.index >= start && match.index < end)) continue;
-      if (!/^(?:artium-axi |npx -y @knowttl\/)?[^\s`'"]+-axi(?:\s|$)/.test(match[2])) return output2;
+      if (!/^(?:artium-axi |npx -y @knowttl\/)?[^\s`'"]+-axi(?:\s|$)/.test(match[2])) return output3;
       const preceding = span.value.slice(0, match.index);
       if (/(?:^|\n)[ \t]*Valid flags for $/.test(preceding) && match[1] === "`" && match[3] === "`") continue;
-      if (!/(?:^|\n|\S[`'"])[ \t]*(?:(?:Run|Use|run|use|Verify with|If you're unsure, run|Check current state before trying again:|or(?:, if you're unsure, run)?)[ \t]+)?$/.test(preceding)) return output2;
+      if (!/(?:^|\n|\S[`'"])[ \t]*(?:(?:Run|Use|run|use|Verify with|If you're unsure, run|Check current state before trying again:|or(?:, if you're unsure, run)?)[ \t]+)?$/.test(preceding)) return output3;
       const wrapped = match[2].startsWith(`artium-axi ${tool}`);
       if (executable.test(match[2])) {
-        if (!match[3]) return output2;
+        if (!match[3]) return output3;
         commandEdit2(match.index + 1, match.index + 1 + match[2].length, wrapped);
       }
     }
   }
   for (const offset of [.../* @__PURE__ */ new Set([...insertions.keys(), ...removals.keys()])].sort((a, b) => b - a)) {
-    output2 = output2.slice(0, offset) + (insertions.get(offset) ?? "") + output2.slice(removals.get(offset) ?? offset);
+    output3 = output3.slice(0, offset) + (insertions.get(offset) ?? "") + output3.slice(removals.get(offset) ?? offset);
   }
-  return output2;
+  return output3;
 }
 function managedFlagRanges(command, tool) {
   const tokens = [...command.matchAll(/(?:[^\s;'"`]+|'[^']*'|"(?:\\.|[^"\\])*")+|;/g)];
@@ -33845,10 +33867,10 @@ function hostedHelp(help, tool, flags, commands2) {
     (match, separator) => separator ? `; artium-axi ${tool}` : match
   )).replace(new RegExp("`(?:npx -y @knowttl/)?" + tool + "(?=\\s|`)([^\\r\\n`]*`)", "g"), "`artium-axi " + tool + "$1").replace(new RegExp(`^([ 	]*cat [^\\r\\n|]+ \\| )(?:npx -y @knowttl/)?${tool}(?=\\s|$)`, "gm"), `$1artium-axi ${tool}`).replace(new RegExp(`\\buse ${tool} entry search\\b`, "g"), `use artium-axi ${tool} entry search`);
 }
-function jsonHelp(output2) {
-  const parsed = JSON.parse(output2);
+function jsonHelp(output3) {
+  const parsed = JSON.parse(output3);
   if (typeof parsed.help !== "string" && !(Array.isArray(parsed.help) && parsed.help.every((item) => typeof item === "string"))) return { spans: [], document: parsed };
-  const tokens = [...output2.matchAll(/"(?:\\[\s\S]|[^"\\])*"|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?|true|false|null|[{}\[\]:,]/g)];
+  const tokens = [...output3.matchAll(/"(?:\\[\s\S]|[^"\\])*"|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?|true|false|null|[{}\[\]:,]/g)];
   const spans = [];
   let index = 0;
   let helpFields = 0;
@@ -33876,8 +33898,8 @@ function jsonHelp(output2) {
   value(false, true);
   return { spans: helpFields === 1 ? spans : [], document: parsed };
 }
-function toonHelp(output2) {
-  const lines = [...output2.matchAll(/[^\r\n]*(?:\r\n|\n|$)/g)].filter((line) => line[0]);
+function toonHelp(output3) {
+  const lines = [...output3.matchAll(/[^\r\n]*(?:\r\n|\n|$)/g)].filter((line) => line[0]);
   const spans = [];
   const validation = lines.map((line) => line[0].replace(/\r?\n$/, ""));
   let helpFields = 0;
@@ -33958,8 +33980,8 @@ accessExpiresAt: ${user.accessExpiresAt}
 }
 function toolsView(tools) {
   if (!tools.length) return "tools: 0 available\nreason: No enabled runtime tool is available through your assigned roles.\ncontact: Ask an administrator to check your role assignments and enabled tools.\nnext[1]:\n  - artium-axi whoami\n";
-  return `tools[${tools.length}]{name,status,version}:
-${tools.map((tool) => `  ${tool.name},${tool.status},${JSON.stringify(tool.version)}`).join("\n")}
+  return `tools[${tools.length}]{name,status,version,readOnly}:
+${tools.map((tool) => `  ${tool.name},${tool.status},${JSON.stringify(tool.version)},${tool.readOnly ?? true}`).join("\n")}
 next[2]:
   - artium-axi tools show ${tools[0].name}
   - artium-axi ${tools[0].name} ${toolManifests[tools[0].name].discovery.example.join(" ")}
@@ -33973,6 +33995,7 @@ function toolView(tool) {
   return `tool: ${tool.name}
 version: ${JSON.stringify(tool.version)}
 status: ${tool.status}
+readOnly: ${tool.readOnly ?? true}
 commands[${commands2.length}]: ${commands2.join(",")}
 example: artium-axi ${tool.name} ${manifest.discovery.example.join(" ")}
 upstreamHelp: ${JSON.stringify(help)}
@@ -34055,15 +34078,15 @@ function claudeSettings(path, executable) {
   if (!Array.isArray(sessions) || sessions.some((entry) => !object2(entry) || !Array.isArray(entry.hooks) || entry.hooks.some((hook) => !object2(hook)))) {
     throw new ArtiumError("INVALID_INPUT", "Claude SessionStart hooks have an unsupported shape; no installation was written.");
   }
-  const managed = { type: "command", command: process.execPath, args: [executable, "tools"], statusMessage: hookName };
+  const managed2 = { type: "command", command: process.execPath, args: [executable, "tools"], statusMessage: hookName };
   let found = false;
   const merged = sessions.map((entry) => ({ ...entry, hooks: entry.hooks.flatMap((hook) => {
     if (hook.statusMessage !== hookName) return [hook];
     if (found) return [];
     found = true;
-    return [managed];
+    return [managed2];
   }) }));
-  if (!found) merged.push({ hooks: [managed] });
+  if (!found) merged.push({ hooks: [managed2] });
   settings.hooks = { ...hooks, SessionStart: merged };
   return JSON.stringify(settings, null, 2) + "\n";
 }
@@ -34224,24 +34247,199 @@ next: artium-axi tools
   throw new ArtiumError("DEVICE_CODE_EXPIRED");
 }
 
+// src/cli/managed-session.ts
+import { fstatSync, writeSync } from "node:fs";
+import { Socket } from "node:net";
+
+// src/server/runner/scan.ts
+function prefixLengths(bytes) {
+  const lengths = new Uint32Array(bytes.length);
+  let length = 0;
+  for (let index = 1; index < bytes.length; index++) {
+    while (length > 0 && bytes[index] !== bytes[length]) length = lengths[length - 1];
+    if (bytes[index] === bytes[length]) length++;
+    lengths[index] = length;
+  }
+  return lengths;
+}
+var SecretScanner = class {
+  #patterns;
+  #positions;
+  #matched = false;
+  constructor(secrets) {
+    const forms = /* @__PURE__ */ new Set();
+    for (const secret of secrets) {
+      if (secret.length === 0) throw new Error("Secret values must be nonempty");
+      const bytes = Buffer.from(secret, "utf8");
+      forms.add(secret);
+      forms.add(bytes.toString("base64"));
+      forms.add(bytes.toString("base64url"));
+      forms.add(encodeURIComponent(secret));
+      forms.add(JSON.stringify(secret).slice(1, -1));
+    }
+    this.#patterns = [...forms].map((form) => {
+      const bytes = Buffer.from(form, "utf8");
+      return { bytes, prefixes: prefixLengths(bytes) };
+    });
+    this.#positions = {
+      stdout: new Uint32Array(this.#patterns.length),
+      stderr: new Uint32Array(this.#patterns.length)
+    };
+  }
+  scan(stream, chunk) {
+    if (this.#matched) return true;
+    const positions = this.#positions[stream];
+    for (let index = 0; index < this.#patterns.length; index++) {
+      const { bytes, prefixes } = this.#patterns[index];
+      let position = positions[index];
+      for (const byte of chunk) {
+        while (position > 0 && byte !== bytes[position]) position = prefixes[position - 1];
+        if (byte === bytes[position]) position++;
+        if (position === bytes.length) {
+          this.#matched = true;
+          return true;
+        }
+      }
+      positions[index] = position;
+    }
+    return false;
+  }
+};
+
+// src/cli/managed-session.ts
+var sessionSchema = external_exports.strictObject({
+  serverUrl: external_exports.string().url(),
+  accessToken: external_exports.string().min(1),
+  refreshToken: external_exports.string().min(1).optional(),
+  status: external_exports.literal("authenticated").optional(),
+  accessExpiresAt: external_exports.number().int().optional(),
+  familyExpiresAt: external_exports.number().int().optional()
+});
+var ManagedSession = class _ManagedSession {
+  constructor(session, channel) {
+    this.session = session;
+    this.channel = channel;
+    this.secrets = [session.accessToken, ...session.refreshToken ? [session.refreshToken] : []];
+  }
+  session;
+  channel;
+  secrets;
+  output = { stdout: "", stderr: "" };
+  static async read() {
+    try {
+      for (const fd of [3, 4]) {
+        const stat = fstatSync(fd);
+        if (!stat.isFIFO() && !stat.isSocket()) throw new Error();
+      }
+      writeSync(4, Buffer.alloc(0));
+      const input2 = new Socket({ fd: 3, readable: true, writable: false });
+      const chunks = [];
+      let bytes = 0;
+      for await (const chunk of input2) {
+        bytes += chunk.length;
+        if (bytes > 64 * 1024) {
+          input2.destroy();
+          throw new Error();
+        }
+        chunks.push(chunk);
+      }
+      const session = sessionSchema.parse(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+      const channel = new Socket({ fd: 4, readable: false, writable: true });
+      channel.on("error", () => {
+      });
+      return new _ManagedSession(session, channel);
+    } catch {
+      throw new ArtiumError(
+        "INVALID_INPUT",
+        "Managed session input or private descriptors are invalid.",
+        "Supply session JSON on inherited pipe fd 3 and a writable private pipe on fd 4; close fd 3 after sending JSON."
+      );
+    }
+  }
+  checkServer(serverUrl) {
+    if (this.session.serverUrl.replace(/\/$/, "") !== serverUrl) throw new ArtiumError("SESSION_SERVER_MISMATCH");
+  }
+  async authenticated(request, refresh) {
+    try {
+      return await request(this.session.accessToken);
+    } catch (error62) {
+      if (!(error62 instanceof ArtiumError) || error62.code !== "TOKEN_EXPIRED" || !this.session.refreshToken) throw error62;
+    }
+    const parsed = loginResponseSchema.safeParse(await refresh(this.session.refreshToken));
+    if (!parsed.success || parsed.data.status !== "authenticated" || !parsed.data.accessToken || !parsed.data.refreshToken) {
+      throw new ArtiumError("INVALID_RESPONSE");
+    }
+    this.session = { serverUrl: this.session.serverUrl, ...parsed.data };
+    this.secrets.push(parsed.data.accessToken, parsed.data.refreshToken);
+    try {
+      await new Promise((resolve3, reject) => {
+        this.channel.write(`${JSON.stringify(this.session)}
+`, (error62) => error62 ? reject(error62) : resolve3());
+      });
+    } catch {
+      throw new ArtiumError(
+        "INVALID_INPUT",
+        "Managed session rotation could not be returned.",
+        "Recover the session through the caller; do not retry using the old refresh token."
+      );
+    }
+    return request(this.session.accessToken);
+  }
+  write(stream, text2) {
+    this.output[stream] += text2;
+  }
+  flush() {
+    this.channel.destroy();
+    const scanner = new SecretScanner(this.secrets);
+    if (scanner.scan("stdout", Buffer.from(this.output.stdout)) || scanner.scan("stderr", Buffer.from(this.output.stderr))) {
+      throw new ArtiumError("SECRET_IN_OUTPUT");
+    }
+    process.stdout.write(this.output.stdout);
+    process.stderr.write(this.output.stderr);
+  }
+};
+
 // src/cli/main.ts
+var managed;
+function output2(stream, text2) {
+  if (managed) managed.write(stream, text2);
+  else process[stream].write(text2);
+}
 async function main(args) {
+  const managedMode = args[0] === "--managed-session";
+  if (managedMode) {
+    args = args.slice(1);
+    if (["login", "passwd", "logout", "setup"].includes(args[0])) {
+      throw new ArtiumError(
+        "INVALID_INPUT",
+        "This command is unavailable in managed session mode.",
+        "The caller must acquire and manage tokens; use managed mode for authenticated calls."
+      );
+    }
+    managed = await ManagedSession.read();
+  }
+  if (args.length === 1 && args[0] === "--version") {
+    output2("stdout", `${cliVersion}
+`);
+    return;
+  }
   const prefixHelp = args[0] === "--help";
   if (prefixHelp) args = args.slice(1);
   const command = args[0];
   const help = helpCommand(prefixHelp ? [...args, "--help"] : args, prefixHelp);
   if (prefixHelp && !help) throw new ArtiumError("INVALID_INPUT", void 0, "Use artium-axi --help for commands.");
   if (help) {
-    process.stdout.write(commandHelp(help));
+    output2("stdout", commandHelp(help));
     return;
   }
   if (command === "setup") {
-    process.stdout.write(await setup(args.slice(1)));
+    output2("stdout", await setup(args.slice(1)));
     return;
   }
   if (command === "doctor") {
     if (args.length !== 1) throw new ArtiumError("INVALID_INPUT", void 0, "Use artium-axi doctor.");
-    await doctor();
+    if (managed) await doctor(() => new Client(process.env, managed), (text2) => output2("stdout", text2));
+    else await doctor();
     return;
   }
   if (command === "login" || command === "passwd") {
@@ -34276,14 +34474,14 @@ async function main(args) {
         return parsed.data;
       });
       if (session.status === "password-change-required") throw new ArtiumError("PASSWORD_CHANGE_REQUIRED");
-      process.stdout.write("status: authenticated\nnext: artium-axi tools\n");
+      output2("stdout", "status: authenticated\nnext: artium-axi tools\n");
     } else {
       await client2.changePassword(async (session) => {
         const newPassword = await readPassword(stdin);
         const currentPassword = session.status === "authenticated" ? await readPassword(false, "ARTIUM_AXI_CURRENT_PASSWORD") : void 0;
         return { newPassword, ...currentPassword === void 0 ? {} : { currentPassword } };
       });
-      process.stdout.write("status: password-changed\nnext: artium-axi login --username <username> --password-stdin\n");
+      output2("stdout", "status: password-changed\nnext: artium-axi login --username <username> --password-stdin\n");
     }
     return;
   }
@@ -34308,10 +34506,10 @@ async function main(args) {
         return false;
       }
     });
-    process.stdout.write(`status: logged-out
+    output2("stdout", `status: logged-out
 remoteRevocation: ${verified ? "verified" : "unverified"}
 `);
-    if (!verified) process.stdout.write("next: Remote revocation is unverified. The local tokens were removed.\n");
+    if (!verified) output2("stdout", "next: Remote revocation is unverified. The local tokens were removed.\n");
     return;
   }
   const home = args.length === 0;
@@ -34322,25 +34520,25 @@ remoteRevocation: ${verified ? "verified" : "unverified"}
     throw new ArtiumError("INVALID_INPUT", "Unknown command, argument or flag.", "Use artium-axi --help for commands or artium-axi <command> --help for valid flags.");
   }
   const input2 = home || listing || whoami ? void 0 : await toolInput(command, args.slice(1));
-  const client = new Client();
-  const homeSession = home ? client.sessions.read() : void 0;
-  if (home && !homeSession) throw new ArtiumError("TOKEN_INVALID", void 0, "Run artium-axi login --username <username> --password-stdin.");
+  const client = new Client(process.env, managed);
+  const homeSession = home && !managed ? client.sessions.read() : void 0;
+  if (home && !managed && !homeSession) throw new ArtiumError("TOKEN_INVALID", void 0, "Run artium-axi login --username <username> --password-stdin.");
   const result = await client.authenticated(home || whoami ? "/v1/me" : `/v1/tools${listing ? "" : `/${command}/run`}`, home || listing || whoami ? "GET" : "POST", input2, homeSession);
   if (home || whoami) {
     const parsed = meResponseSchema.safeParse(result);
     if (!parsed.success) throw new ArtiumError("INVALID_RESPONSE");
-    let output2 = identityView(parsed.data, client.serverUrl);
+    let view = identityView(parsed.data, client.serverUrl);
     if (home) {
       const tools = toolsResponseSchema.safeParse(await client.authenticated("/v1/tools", "GET", void 0, homeSession));
       if (!tools.success) throw new ArtiumError("INVALID_RESPONSE");
       const executable = resolve2(process.argv[1]);
       const local = relative(homedir3(), executable);
       const bin = local && !isAbsolute(local) && !local.startsWith(`..${sep}`) && local !== ".." ? `~${sep}${local}` : executable;
-      output2 = `bin: ${JSON.stringify(bin)}
+      view = `bin: ${JSON.stringify(bin)}
 description: Run managed upstream tools through one local sign-in.
-${output2}${toolsView(tools.data.tools)}`;
+${view}${toolsView(tools.data.tools)}`;
     }
-    process.stdout.write(output2);
+    output2("stdout", view);
   } else if (listing) {
     const parsed = toolsResponseSchema.safeParse(result);
     if (!parsed.success) throw new ArtiumError("INVALID_RESPONSE");
@@ -34348,23 +34546,30 @@ ${output2}${toolsView(tools.data.tools)}`;
     if (detail) {
       const tool = tools.find((tool2) => tool2.name === args[2]);
       if (!tool) throw new ArtiumError("TOOL_NOT_GRANTED", "The tool is not available to your account.", "Ask an administrator to check your role assignments and enabled tools.");
-      process.stdout.write(toolView(tool));
-    } else process.stdout.write(toolsView(tools));
+      output2("stdout", toolView(tool));
+    } else output2("stdout", toolsView(tools));
   } else {
     const parsed = runSuccessSchema.safeParse(result);
     if (!parsed.success || parsed.data.source !== command) throw new ArtiumError("INVALID_RESPONSE");
     const { stdout, stderr, exitCode, truncated } = parsed.data;
-    if (truncated.stdout || truncated.stderr) process.stderr.write(`artium-axi: output truncated (${["stdout", "stderr"].filter((stream) => truncated[stream]).join(", ")}).
+    if (truncated.stdout || truncated.stderr) output2("stderr", `artium-axi: output truncated (${["stdout", "stderr"].filter((stream) => truncated[stream]).join(", ")}).
 `);
-    process.stdout.write(rewriteSuggestions(stdout, command, truncated.stdout));
-    process.stderr.write(rewriteSuggestions(stderr, command, truncated.stderr));
+    output2("stdout", rewriteSuggestions(stdout, command, truncated.stdout));
+    output2("stderr", rewriteSuggestions(stderr, command, truncated.stderr));
     process.exitCode = exitCode;
   }
 }
 function printError(response) {
-  process.stdout.write(`error:
+  output2("stdout", `error:
 ${Object.entries(response.error).map(([key, value]) => `  ${key}: ${JSON.stringify(value)}`).join("\n")}
 `);
   process.exitCode = errors[response.error.code].exitCode;
 }
-main(process.argv.slice(2)).catch((error62) => printError(errorResponse(error62 instanceof ArtiumError ? error62 : new ArtiumError("INTERNAL_ERROR"), randomUUID3())));
+main(process.argv.slice(2)).catch((error62) => printError(errorResponse(error62 instanceof ArtiumError ? error62 : new ArtiumError("INTERNAL_ERROR"), randomUUID3()))).then(() => {
+  try {
+    managed?.flush();
+  } catch {
+    managed = void 0;
+    printError(errorResponse(new ArtiumError("SECRET_IN_OUTPUT"), randomUUID3()));
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowttl/artium-axi",
-  "version": "0.0.0",
+  "version": "0.0.3",
   "description": "Client CLI and embedded skill for the Artium managed tools server.",
   "license": "MIT",
   "type": "module",