totemlayer 0.1.44 → 0.1.63

package/bin/sdk/types.d.ts

@@ -1,3 +1,39 @@
+export interface AgentMemoryControls {
+  enabled: boolean;
+  knowledgeRetentionDays: number;
+  workingRetentionDays: number;
+}
+export interface AgentMemoryEntry {
+  id: string;
+  section: "notes" | "workingMemory";
+  text: string;
+  reinforcedAt: string;
+  pinned: boolean;
+  expiresAt: string | null;
+  sourceKey?: string;
+  sourceEventId?: string;
+}
+
+export interface AgentMemory {
+  agentId: string;
+  notes: string;
+  workingMemory: string;
+  version: number;
+  updatedAt: string | null;
+  updatedBy: string | null;
+  controls: AgentMemoryControls;
+  entries: AgentMemoryEntry[];
+  forgottenCount: number;
+  active: { pendingMessages: number; queuedChats: number; openTasks: number };
+}
+
+export interface AgentProfileInput {
+  name: string;
+  localPart: string;
+  description?: string;
+  creationContext: { background?: string; decisions?: string; nextSteps?: string };
+}
+
 export type Metadata = Record<string, unknown>;
 export type JsonValue = null | boolean | number | string | JsonValue[] | {
     [key: string]: JsonValue;
@@ -22,6 +58,8 @@ export interface AgentRuntimeStatus {
 }
 
 export interface Agent {
+  /** Own authenticated identity only; automatically loaded at connection. */
+  memory?: AgentMemory;
   /** Absent from public discovery; a connected MCP client alone is not a ready listener. */
   runtime?: AgentRuntimeStatus;
     actionMode?: "ask_me" | "full_access";
@@ -652,6 +690,7 @@ export type MessageHandler = (message: IncomingMessage) => void | Promise<void>;
 export interface ListenOptions {
     /** Customer-side policy. Screens message/file plaintext before invoking the handler. */
     inspector?: import("./inspector.js").LocalInspector;
+    /** Healthy inbox checks default to 5000 ms; an explicit host override is preserved. */
     pollIntervalMs?: number;
     /** Receives handler and transport failures; polling continues afterward. */
     onError?: (error: Error) => void;
@@ -703,6 +742,8 @@ export interface ChatDetail {
     previousCursor?: string | null;
 }
 export interface RuntimeHeartbeat {
+  listenerReady?: boolean;
+  listenerKind?: "mcp" | "runtime";
     operationalStatesSupported?: boolean;
     ready?: boolean;
     state?: string;
@@ -726,3 +767,24 @@ export interface NetworkActivityPage extends Page<NetworkActivity> {
   actionMode: "ask_me" | "full_access";
   actionModeVersion: number;
 }
+
+export interface AgentMemorySearch {
+  query?: string;
+  includeHistory?: boolean;
+  before?: number;
+  limit?: number;
+}
+export interface AgentMemoryHistory {
+  data: Array<{
+    id: string;
+    version: number;
+    notes: string;
+    workingMemory: string;
+    source: string;
+    sourceEventId: string | null;
+    createdAt: string;
+    current: boolean;
+    excerpt: string;
+  }>;
+  nextCursor: string | null;
+}

package/bin/startup-diagnostics.mjs

@@ -0,0 +1,168 @@
+// Public diagnostics contain fixed descriptions only. Never log exception messages,
+// provider output, command arguments, paths, or credentials from a failed startup.
+export const HOST_APPROVAL_RECOVERY =
+  "Stop retrying. Ask the owner to inspect this command in the host app's approval or automatic review controls. If no approval path is available, contact the host's support with the denial. Resume once after the owner resolves it; do not bypass the policy or change agents.";
+
+const causes = {
+  HOST_APPROVAL_DENIED: [
+    "The host denied approval to execute the startup command.",
+    HOST_APPROVAL_RECOVERY,
+    false,
+  ],
+  EADDRINUSE: [
+    "The listener could not bind because its port or socket is already in use.",
+    "Inspect the process using the configured port or socket; stop a duplicate listener or choose an available endpoint before starting this profile again.",
+  ],
+  EACCES: [
+    "The operating system denied access to a startup resource.",
+    "Check the owner's access to the executable, private state directory, and configured port; repair the specific permission before restarting.",
+  ],
+  EPERM: [
+    "The operating system denied the startup operation.",
+    "Inspect the host's process and filesystem restrictions and have the owner resolve the denied operation before restarting.",
+  ],
+  ENOENT: [
+    "A required startup executable or file was not found.",
+    "Check the selected executable and private configuration paths; install or restore the missing resource before restarting.",
+  ],
+  ECONNREFUSED: [
+    "The configured service refused the connection.",
+    "Start the configured model or service and check its endpoint before restarting this profile.",
+  ],
+  ENOTFOUND: [
+    "The configured service hostname could not be resolved.",
+    "Check the configured hostname and network DNS, then restart this profile.",
+  ],
+  ETIMEDOUT: [
+    "The startup connection timed out.",
+    "Check the service endpoint and network availability before restarting this profile.",
+  ],
+  RUN_TIMEOUT: [
+    "The executor did not finish the controlled readiness reply before its deadline.",
+    "Check the selected executor and model availability before restarting this profile.",
+  ],
+  PROVIDER_AUTH_REQUIRED: [
+    "The selected inference provider credential is missing or unavailable.",
+    "Restore the selected provider credential in this host's secret environment before restarting. Never copy another agent's key.",
+  ],
+  RUNTIME_AUTHORIZATION_REJECTED: [
+    "Totem rejected the profile's credential or access.",
+    "Reauthorize this agent with totem login --reauthorize. Never copy another agent's key.",
+  ],
+  AGENT_IDENTITY_MISMATCH: [
+    "The authenticated agent does not match the saved profile.",
+    "Inspect this profile's agent and origin; reconnect the intended agent without replacing another agent's configuration.",
+  ],
+  ISOLATION_UNAVAILABLE: [
+    "The selected executor's required process isolation is unavailable.",
+    "Repair the supported isolation backend on this host before restarting; do not disable containment.",
+  ],
+  PRIVACY_BOUNDARY_UNAVAILABLE: [
+    "The executor's required privacy boundary is unavailable.",
+    "Repair the configured privacy boundary before restarting; do not bypass it.",
+  ],
+  AGENT_AUTH_REQUIRED: [
+    "The selected agent client is not authenticated.",
+    "Sign in to the selected client on this host, then explicitly start this profile once.",
+  ],
+  AGENT_QUOTA_EXCEEDED: [
+    "The selected agent provider rejected startup because its usage quota is exhausted.",
+    "Inspect the selected provider's usage limits and resume once capacity is available.",
+  ],
+  AGENT_CLI_INCOMPATIBLE: [
+    "The installed agent CLI does not support the required startup contract.",
+    "Install a supported version of the selected client, then start this profile once.",
+  ],
+  HARNESS_SETUP_REQUIRED: [
+    "The selected host has not completed its native receiver setup.",
+    "Complete the selected host's supported setup and inspect its approval controls before starting this profile.",
+  ],
+  READINESS_UNSUPPORTED: [
+    "The installed adapter cannot verify the controlled readiness check.",
+    "Update the selected adapter to a version that supports receive, wake, and reply verification before claiming readiness.",
+  ],
+  AGENT_NOT_INSTALLED: [
+    "The selected agent executable is not installed or cannot be located.",
+    "Install the selected agent client and check this host's executable path before restarting.",
+  ],
+  AGENT_START_FAILED: [
+    "The executor process could not be launched.",
+    "Check that the selected executable exists and the owner can run it on this host.",
+  ],
+  AGENT_EXIT_FAILED: [
+    "The executor exited with a nonzero status during startup.",
+    "Inspect the selected executor's local diagnostics and sign-in state before restarting; do not share credentials or raw provider output.",
+  ],
+  INVALID_AGENT_RESULT: [
+    "The executor returned an invalid readiness response.",
+    "Check the selected adapter's response format and configured model before restarting.",
+  ],
+  READINESS_CHALLENGE_FAILED: [
+    "Totem could not supply a valid controlled readiness challenge.",
+    "Check Totem connectivity and the installed receiver version before restarting this profile.",
+  ],
+  READINESS_GENERATION_FAILED: [
+    "The selected executor failed while generating the controlled readiness reply; it supplied no recognized cause.",
+    "Inspect the selected executor's local diagnostics and authorization before restarting this profile.",
+  ],
+  READINESS_REPLY_REJECTED: [
+    "Totem did not accept the controlled readiness reply.",
+    "Check that the selected executor returns the exact readiness challenge response and that the runtime session is current before restarting.",
+  ],
+  READINESS_REPLY_INVALID: [
+    "The executor did not return the exact controlled readiness response.",
+    "Check the selected adapter's output contract and repeat the readiness check once after repair.",
+  ],
+  READINESS_EXPIRED: [
+    "The controlled readiness challenge expired before it completed.",
+    "Check executor latency and start a fresh runtime session to obtain a new challenge.",
+  ],
+  RUNTIME_SUPERSEDED: [
+    "Another runtime session owns this connection credential.",
+    "Inspect the existing listener and use its session; stop it explicitly before replacing it. Do not start duplicate workers.",
+  ],
+  BACKGROUND_START_TIMEOUT: [
+    "The background worker did not confirm startup before its deadline.",
+    "Inspect totem status for this profile and the selected executor's local diagnostics before starting it again.",
+  ],
+  STARTUP_CAUSE_UNAVAILABLE: [
+    "Startup failed without a recognized underlying cause.",
+    "Inspect this profile with totem status and the selected executor's local diagnostics before restarting. Share error codes, not credentials or raw provider output.",
+  ],
+};
+
+const known = (code) => typeof code === "string" && Object.hasOwn(causes, code);
+
+export function startupDiagnostic(error) {
+  const chain = [];
+  const seen = new Set();
+  for (
+    let item = error;
+    item && typeof item === "object" && chain.length < 8 && !seen.has(item);
+    item = item.cause
+  ) {
+    seen.add(item);
+    chain.push(item);
+  }
+  const denied = chain.some(
+    (item) =>
+      ["HOST_APPROVAL_DENIED", "APPROVAL_DENIED", "POLICY_DENIED"].includes(item.code) ||
+      /(?:rejected:\s*)?blocked by policy|automatic (?:approval )?review rejected|approval (?:was )?denied/i.test(
+        String(item.message ?? ""),
+      ),
+  );
+  const match = chain
+    .toReversed()
+    .find((item) => known(item.code) || known(item.causeCode) || [401, 403].includes(item.status));
+  const causeCode = denied
+    ? "HOST_APPROVAL_DENIED"
+    : match
+      ? known(match.code)
+        ? match.code
+        : known(match.causeCode)
+          ? match.causeCode
+          : "RUNTIME_AUTHORIZATION_REJECTED"
+      : "STARTUP_CAUSE_UNAVAILABLE";
+  const [cause, recovery, retryable = true] = causes[causeCode];
+  return { causeCode, cause, recovery, retryable };
+}

package/bin/totem.mjs

@@ -239,9 +239,9 @@ function compactDigest(value) {
 function help() {
   writeBrand();
   writeHelpBody(`Start here
-  Install once          npm install --global https://totemlayer.com/downloads/totemlayer-0.1.44.tgz
+  Install once          npm install --global https://totemlayer.com/downloads/totemlayer-0.1.63.tgz
   Confirm installation totem --version
-  Run one-off           npx --yes --package https://totemlayer.com/downloads/totemlayer-0.1.44.tgz totem --help
+  Run one-off           npx --yes --package https://totemlayer.com/downloads/totemlayer-0.1.63.tgz totem --help
 
 Connect once and receive messages and approved Mission work
   Select Codex, Claude, a local model, or an owner-configured CLI/HTTP agent.
@@ -255,7 +255,9 @@ Agent messaging and local runtime
   totem network --help
   totem network run --provider qwen-local --model qwen3.5-9b
 
-Connect an AI app through MCP
+Connect any AI agent or personal assistant through MCP
+  totem mcp config
+  totem mcp config --transport stdio --key-file /absolute/path/to/agent.key
   totem mcp
 
 Authorization handshake
@@ -1781,6 +1783,18 @@ async function main() {
     return;
   }
   if (process.argv[2] === "mcp") {
+    if (process.argv[3] === "config") {
+      const { configureTotemMcp } = await import("./mcp-install.mjs");
+      try {
+        process.stdout.write(await configureTotemMcp(process.argv.slice(4)));
+      } catch (error) {
+        process.stderr.write(
+          `${error instanceof Error ? error.message : "Could not export MCP settings."}\n`,
+        );
+        process.exitCode = 1;
+      }
+      return;
+    }
     if (process.argv[3] === "install" || process.argv[3] === "--help" || process.argv[3] === "-h") {
       const { installTotemMcp } = await import("./mcp-install.mjs");
       try {

package/bin/worker-core/adapters.mjs

@@ -27,9 +27,9 @@ function integer(value, fallback, maximum) {
   return result;
 }
 
-function childEnvironment(values) {
+function childEnvironment(values, inheritSystemEnvironment = true) {
   const environment = {};
-  for (const key of SYSTEM_ENV) {
+  for (const key of inheritSystemEnvironment ? SYSTEM_ENV : []) {
     if (process.env[key] !== undefined) environment[key] = process.env[key];
   }
   for (const [key, value] of Object.entries(values ?? {})) {
@@ -58,7 +58,7 @@ export function createCommandAdapter(config) {
     throw new WorkerError("INVALID_ADAPTER_CONFIG");
   }
   const args = [...(config.args ?? [])];
-  const env = childEnvironment(config.env);
+  const env = childEnvironment(config.env, config.inheritSystemEnvironment !== false);
   const timeoutMs = integer(config.timeoutMs, 15 * 60_000, 24 * 60 * 60_000);
   const maxOutputBytes = integer(config.maxOutputBytes, 1024 * 1024, 16 * 1024 * 1024);
   const parseResult = config.parseResult ?? ((output) => ({ status: "completed", output }));
@@ -82,7 +82,12 @@ export function createCommandAdapter(config) {
         const diagnosticFailure = (error, exitCode) => {
           if (config.captureFailure)
             Object.defineProperty(error, "privateProviderDiagnostic", {
-              value: { command: config.command, exitCode, stderr: diagnosticOutput, stdout: output },
+              value: {
+                command: config.command,
+                exitCode,
+                stderr: diagnosticOutput,
+                stdout: output,
+              },
               enumerable: false,
             });
           return error;
@@ -127,8 +132,8 @@ export function createCommandAdapter(config) {
             windowsHide: true,
             stdio: ["pipe", "pipe", "pipe"],
           });
-        } catch {
-          reject(new WorkerError("AGENT_START_FAILED"));
+        } catch (error) {
+          reject(Object.assign(new WorkerError("AGENT_START_FAILED"), { cause: error }));
           return;
         }
         const timeout = setTimeout(() => stop("RUN_TIMEOUT"), timeoutMs);
@@ -144,18 +149,21 @@ export function createCommandAdapter(config) {
         child.stderr.on("data", (chunk) => {
           bytes += chunk.length;
           if (bytes > maxOutputBytes) stop("OUTPUT_LIMIT_EXCEEDED");
-          else if (config.classifyFailure || config.captureFailure) diagnosticOutput += chunk.toString("utf8");
+          else if (config.classifyFailure || config.captureFailure)
+            diagnosticOutput += chunk.toString("utf8");
         });
         child.stdin.on("error", () => {
           /* A failed child can close stdin early. */
         });
-        child.on("error", () => {
-          failure ??= new WorkerError("AGENT_START_FAILED");
+        child.on("error", (error) => {
+          failure ??= Object.assign(new WorkerError("AGENT_START_FAILED"), { cause: error });
         });
         child.on("close", (code) => {
           clearTimeout(timeout);
           clearTimeout(killTimer);
           signal?.removeEventListener("abort", cancel);
+          // A successful foreground turn cannot leave background tools behind.
+          if (config.inheritSystemEnvironment === false) kill("SIGKILL");
           if (failure) {
             kill("SIGKILL");
             return reject(diagnosticFailure(failure, code));
@@ -163,9 +171,13 @@ export function createCommandAdapter(config) {
           if (code !== 0) {
             try {
               return reject(
-                diagnosticFailure(new WorkerError(
-                  config.classifyFailure?.(`${diagnosticOutput}\n${output}`) ?? "AGENT_EXIT_FAILED",
-                ), code),
+                diagnosticFailure(
+                  new WorkerError(
+                    config.classifyFailure?.(`${diagnosticOutput}\n${output}`) ??
+                      "AGENT_EXIT_FAILED",
+                  ),
+                  code,
+                ),
               );
             } catch {
               return reject(diagnosticFailure(new WorkerError("AGENT_EXIT_FAILED"), code));
@@ -174,7 +186,12 @@ export function createCommandAdapter(config) {
           try {
             resolve(validateResult(parseResult(output)));
           } catch (error) {
-            reject(diagnosticFailure(error instanceof WorkerError ? error : new WorkerError("INVALID_AGENT_RESULT"), code));
+            reject(
+              diagnosticFailure(
+                error instanceof WorkerError ? error : new WorkerError("INVALID_AGENT_RESULT"),
+                code,
+              ),
+            );
           }
         });
         // Prompts cannot become argv, executable names, paths, or shell syntax.

package/bin/worker-core/errors.mjs

@@ -1,5 +1,9 @@
 const SAFE_CODES = new Set([
   "INTERNAL_ERROR",
+  "PRIVACY_REVIEW_REQUIRED",
+  "ISOLATION_UNAVAILABLE",
+  "PROVIDER_AUTH_REQUIRED",
+  "AGENT_NOT_INSTALLED",
   "INVALID_AGENT_RESULT",
   "INVALID_ADAPTER_ENV",
   "INVALID_RUNNER_ARGUMENTS",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "totemlayer",
-  "version": "0.1.44",
+  "version": "0.1.63",
   "description": "Cross-platform CLI for TotemLayer agent identity and authorization",
   "type": "module",
   "bin": {

package/scripts/prepare.mjs

@@ -1,13 +1,27 @@
 import { access, readdir, readFile, writeFile } from "node:fs/promises";
 import { transform } from "esbuild";
+import { generateNetworkContract } from "../../../scripts/generate-network-contract.mjs";
+await generateNetworkContract();
 // This candidate rebases coordination on the immutable published 0.1.21 bundle.
 // Its bundled SDK is the release source; do not rebuild it from an older sibling checkout.
 for (const name of [
-  "totem.mjs", "mission-worker.mjs", "mission-coordination.mjs",
-  "sdk/index.js", "sdk/index.d.ts", "sdk/types.d.ts",
-  "network-retry.mjs", "runtime-diagnostics.mjs", "codex-chat-bridge.mjs",
-  "worker-core/adapters.mjs", "worker-core/errors.mjs",
-]) await access(new URL(`../bin/${name}`, import.meta.url));
+  "totem.mjs",
+  "mission-worker.mjs",
+  "mission-coordination.mjs",
+  "sdk/index.js",
+  "sdk/index.d.ts",
+  "sdk/listener.js",
+  "sdk/listener.d.ts",
+  "sdk/types.d.ts",
+  "network-retry.mjs",
+  "runtime-diagnostics.mjs",
+  "codex-chat-bridge.mjs",
+  "codex-human-chat-bridge.mjs",
+  "chat-prompt-limit.mjs",
+  "worker-core/adapters.mjs",
+  "worker-core/errors.mjs",
+])
+  await access(new URL(`../bin/${name}`, import.meta.url));
 
 // Compact the release SDK without rebuilding it from an older sibling source.
 // Retain every module, export, name and declaration; no feature code is removed.
@@ -16,9 +30,15 @@ for (const name of await readdir(sdk)) {
   if (!name.endsWith(".js")) continue;
   const path = new URL(name, sdk);
   const result = await transform(await readFile(path, "utf8"), {
-    loader: "js", target: "es2022", format: "esm",
-    minifyWhitespace: true, minifyIdentifiers: false, minifySyntax: false,
-    treeShaking: false, keepNames: false, legalComments: "eof",
+    loader: "js",
+    target: "es2022",
+    format: "esm",
+    minifyWhitespace: true,
+    minifyIdentifiers: false,
+    minifySyntax: false,
+    treeShaking: false,
+    keepNames: false,
+    legalComments: "eof",
   });
   await writeFile(path, result.code);
 }