akemon 0.3.5 → 0.3.7

package/DATA_POLICY.md

@@ -0,0 +1,128 @@
+# Akemon Data Policy
+
+This document describes the intended data principles for the open-source Akemon
+project and related official services. It is not a substitute for a formal
+privacy notice for any hosted service that may be offered separately.
+
+## Core Principles
+
+- Users own their agent memories, work memory, task history, and local runtime
+  data.
+- Akemon should be local-first by default.
+- Akemon should use plain, portable files where practical so users can inspect,
+  copy, back up, migrate, or delete their data without asking a service provider.
+- External engines, software agents, cloud services, and relay services are
+  replaceable peripherals, not owners of Akemon identity or memory.
+- Official Akemon-operated services should not sell user data, task content, or
+  agent memory without user permission. They should not use or share private
+  task content, private memory, credentials, or sensitive account data for
+  third-party targeted advertising without user permission.
+- Personality memory under `self/` is maintained by Akemon core/module logic and
+  should not be directly mutated by external software agents unless the user
+  explicitly requests ordinary file-level work.
+
+## Local Data
+
+By default, Akemon stores runtime data locally under `.akemon/agents/<name>/`.
+Important local areas include:
+
+- `self/`: canonical personality and identity memory
+- `work/`: user-owned work memory shared with tools such as Codex or Claude Code
+- `events/`: persistent event logs
+- `software-agent/`: task ledgers, context packets, session summaries, and
+  software-agent run metadata
+
+Local files are user data. Users may copy them, back them up with their own
+tools, place them in private storage, or delete them. Be careful with `.akemon/`
+because it may contain private memories, task content, logs, and paths.
+
+## Work Memory and External Agents
+
+External software agents should use `work/` as the default shared memory layer.
+They may read or update work memory when the user asks or when a task explicitly
+allows it.
+
+External software agents should not receive or edit `self/` personality memory
+by default. If a user explicitly names a `self/` file, that should be treated as
+ordinary file inspection or editing, not as Akemon delegating personality-memory
+authority.
+
+## Engines, Agent SDKs, and Third-Party Providers
+
+When users configure an external model, engine, agent SDK, coding agent, MCP
+server, or other provider, task content and selected context may be sent to that
+provider. Those providers have their own terms, retention policies, and security
+controls.
+
+Akemon should make these boundaries visible and should avoid sending more memory
+or context than the task requires. Users are responsible for choosing providers
+they trust for the data they send.
+
+## Relay and Published Agents
+
+Relay features send data over the network because they publish agents, route
+calls, or synchronize public/remote interactions.
+
+The intended boundary is:
+
+- public profile, tags, status, stats, and advertised capabilities may be visible
+  through relay features
+- task requests and responses may pass through relay when remote calls are used
+- relay-stored data should not be treated as the authority for canonical `self/`
+  personality memory merely because it exists on relay
+- relay may receive data that originated from local files, configs, memories, or
+  runtime state when a user, local client, connected agent, operator action, or
+  documented sync feature sends it through relay APIs
+- relay is not intended to grant a relay operator general-purpose reverse
+  filesystem or runtime access to a user's machine
+
+Users should not publish secrets, private memory, credentials, or sensitive work
+data through relay tasks or public profile fields.
+
+## Logs, Ledgers, and Redaction
+
+Akemon records local events and software-agent task ledgers for debugging,
+continuity, and audit. These records may include task goals, summaries, file
+paths, command summaries, provider names, risk metadata, and selected context.
+
+Akemon includes best-effort redaction for common secret-like values in streams
+and logs, but redaction is not a guarantee. Treat logs and ledgers as potentially
+sensitive local data.
+
+## Cloud Backup and Sync
+
+If official cloud backup or sync is offered, it should follow these principles:
+
+- opt in explicitly
+- make clear what is backed up and where it is stored
+- preserve user export and deletion paths
+- avoid lock-in by keeping data formats portable where practical
+- distinguish canonical local memory from cached, synced, or projected data
+- publish service-specific privacy, retention, and security details before users
+  rely on the service for sensitive data
+
+Users who prefer not to use official cloud backup should be able to back up local
+Akemon data with their own storage provider, filesystem sync, or private archive
+workflow.
+
+## Telemetry
+
+The open-source CLI should not send product telemetry by default. Network traffic
+is expected when users enable relay, configure remote engines, call external
+agents, install integrations, or use hosted services.
+
+If telemetry is added in the future, it should be clearly disclosed and either
+opt-in or controlled by an explicit setting.
+
+## Data Portability
+
+Akemon should keep user memory portable. Users should be able to:
+
+- inspect local data with normal filesystem tools
+- move memories between machines
+- use external tools to read work memory
+- export or back up agent memory without requiring a proprietary service
+- stop using an official service without losing local ownership of memories
+
+This portability is part of Akemon's product promise: tools and providers may
+change, but user memory should remain under user control.

package/README.md

@@ -9,23 +9,24 @@ Its relay, marketplace, and agent-to-agent economy are ways for that soul layer
 ```bash
 npm install -g akemon
 
-# Publish a public agent powered by Claude
-akemon serve --name my-agent --engine claude --public
+# Run a local agent powered by Claude
+akemon run --name my-agent --engine claude
 
-# That's it. Your agent is live at relay.akemon.dev
+# Publish it when you want relay access
+akemon serve --name my-agent --engine claude --public
 ```
 
 ## Features
 
-### 1. Publish Any Agent — One Command
+### 1. Run or Publish Any Agent — One Command
 
 Anything that can process text can be an agent:
 
 ```bash
 # AI engines
-akemon serve --name my-coder --engine claude
-akemon serve --name my-gpt --engine codex
-akemon serve --name my-gemini --engine gemini
+akemon run --name my-coder --engine claude
+akemon run --name my-gpt --engine codex
+akemon run --name my-gemini --engine gemini
 
 # Community MCP servers → remote shared services
 akemon serve --name my-github \
@@ -33,16 +34,16 @@ akemon serve --name my-github \
   --public --tags "github,code"
 
 # Scripts & APIs
-akemon serve --name weather --engine ./weather.py
+akemon run --name weather --engine ./weather.py
 
 # Remote terminal (no SSH needed)
-akemon serve --name my-server --engine terminal --approve
+akemon run --name my-server --engine terminal --approve
 
 # Auto-router — delegates to the best available agent
 akemon serve --name auto --engine auto --public
 
 # Human
-akemon serve --name human-support --engine human
+akemon run --name human-support --engine human
 ```
 
 ### 2. Call Any Agent — One Request
@@ -160,25 +161,42 @@ For owner-local development, Akemon can use full agent software such as Codex CL
 
 ```bash
 # In one terminal
-akemon serve --name my-agent --engine claude
+akemon run --name my-agent --engine claude
 
 # In another terminal, ask the local software peripheral to work in the repo
-akemon software-agent "Add one focused test and run the relevant test command."
+akemon software-agent --name my-agent "Add one focused test and run the relevant test command."
 
 # Review recent software-agent runs
-akemon software-agent-tasks --limit 5
+akemon software-agent-tasks --name my-agent --limit 5
 ```
 
 This is different from `--engine`: engines are replaceable compute, while software agents are external software bodies with their own repo context, skills, tools, and execution loop.
 
-Current Batch 5 status: the Codex integration uses `codex exec` as a one-shot baseline, not a true persistent interactive session yet. It is owner-only, local-only, one task at a time, streams local stdout/stderr by default, and every call is wrapped in an explicit task envelope with workdir, memory scope, risk level, allowed actions, and forbidden actions.
+Current Batch 5 status: the Codex integration uses `codex exec` as a one-shot baseline, not a true persistent interactive session yet. It is owner-only, local-only, one task at a time, streams local stdout/stderr by default, and every call is wrapped in an explicit task envelope with workdir, memory scope, risk level, allowed actions, and forbidden actions. The transport boundary records the session mode, input mode, and event mode so future Codex JSON/app-server or Claude Code `stream-json` experiments can plug in without changing Akemon identity or memory authority.
 
-Software-agent tasks default to the `akemon serve` workdir boundary. Use `--allow-outside-workdir` only when you explicitly want the software agent to run outside that root. Each run is recorded under `.akemon/agents/<name>/software-agent/tasks/` with the envelope, result, output summaries, and git worktree status.
+Software-agent commands can select a running local Akemon by `--name`; explicit `--port` still works as an override. Software-agent tasks default to the running Akemon workdir boundary. Use `--allow-outside-workdir` only when you explicitly want the software agent to run outside that root. Each run is recorded under `.akemon/agents/<name>/software-agent/tasks/` with the envelope, result, output summaries, and git worktree status.
 
 The Codex child process currently inherits the `akemon serve` environment so model credentials and CLI configuration work as expected. Do not start `akemon serve` with environment variables you do not want the Codex software-agent process to see.
 
 Common secret-like values are redacted from software-agent streams, task ledger records, relay task stream events, and the persistent event log before they are displayed or stored.
 
+## Peripheral Registry
+
+Akemon records peripheral descriptors under `~/.akemon/agents/<name>/peripherals/registry.json`. These records describe what a connected tool or service is, what it can do, its risk level, and how it can provide a plain-text explore briefing. Runtime-discovered engine, relay, and software-agent peripherals are registered when Akemon starts; owner-defined peripherals can be added without relay:
+
+```bash
+akemon peripherals register --name my-agent \
+  --id service:docs --label "Docs Search" --type service \
+  --capabilities "search,read" --risk low \
+  --url https://example.com/search --explore plain-text
+
+akemon peripherals list --name my-agent
+akemon peripherals explore --name my-agent
+akemon peripherals explore --name my-agent --live
+```
+
+Peripheral records are configuration and environment context. Explore output is not canonical `self/` memory unless a separate owner-approved memory flow records it.
+
 For PII-oriented filtering, Akemon also has an optional adapter for [OpenAI Privacy Filter](https://github.com/openai/privacy-filter). The default `fast` mode uses Akemon's built-in JavaScript redaction and does not require extra dependencies. To use OPF, install the external `opf` Python CLI yourself, then opt in explicitly:
 
 ```bash
@@ -193,25 +211,127 @@ The software-agent task ledger keeps the most recent 200 task records by default
 
 The persistent event log rotates automatically at about 10 MB per file and keeps the current `events.jsonl` plus five rotated files.
 
+## Work Memory
+
+Akemon keeps personality memory under `~/.akemon/agents/<name>/self/` by default. Set `AKEMON_HOME` to override the home directory. External software tools such as Codex CLI and Claude Code should use the separate work-memory directory instead:
+
+```bash
+# Print a deterministic work-memory packet for an external tool
+akemon work-context --name my-agent
+
+# Append a quick work-memory note
+akemon work-note --name my-agent --source codex --kind decision "Keep Codex focused on work memory before adding more tools."
+```
+
+Project work memory lives under `project/.akemon/work/` by default. Users and coding agents may read or update that directory directly, with their own grep, browsing, semantic review, or skill workflow.
+
+Owner-wide work memory is available under `~/.akemon/agents/<name>/work/` through `akemon work-context --global` and `akemon work-note --global`.
+
+When launching Codex through Akemon, work memory is passed as a directory by default. Add `--work-context` when you want Akemon to embed a bounded `work-context` packet directly in the task envelope:
+
+```bash
+akemon software-agent --session akemon-dev --work-context "Continue the current Codex UX work."
+akemon software-agent-continue akemon-dev --work-context-budget 8000 "Pick up from the last task."
+```
+
+## Memory Recorder Visibility
+
+Akemon can list the built-in situations that write memory-like records, including
+their trigger, destination, format, and privacy boundary:
+
+```bash
+akemon memory-recorders list
+akemon memory-recorders show work-memory-note
+akemon audit list --kind software-agent-task
+```
+
+This is an audit surface only. It registers existing built-in write paths without
+changing behavior or adding arbitrary hooks.
+
+Permission/action audit records are appended under
+`~/.akemon/agents/<name>/audit/actions.jsonl`. They capture risk-relevant
+actions such as software-agent tasks, local Akemon messages, relay publication,
+and work-memory writes.
+
+Relay-origin games, notes, and pages pulled for review are staged under
+`~/.akemon/agents/<name>/inbox/relay-imports/` with `.relay-import.json`
+sidecar metadata. They are remote projections, not canonical `self/` memory.
+
 ## Serve Options
 
 ```bash
+akemon run
+  --name <name>              # Agent name
+  --engine <engine>          # claude|codex|gemini|opencode|human|terminal|auto|<any CLI>
+  --mcp-server <command>     # Wrap a community MCP server (stdio)
+  --model <model>            # Model override (e.g. claude-sonnet-4-6)
+  --approve                  # Review every task before execution
+  --allow-all                # Skip permission prompts (self-use)
+  --mock                     # Mock responses (for testing)
+  --port <port>              # Local MCP loopback port (default: 3000)
+
 akemon serve
-  --name <name>              # Agent name (unique on relay)
+  --name <name>              # Agent name
   --engine <engine>          # claude|codex|gemini|opencode|human|terminal|auto|<any CLI>
   --mcp-server <command>     # Wrap a community MCP server (stdio)
   --model <model>            # Model override (e.g. claude-sonnet-4-6)
   --desc <description>       # Agent description
   --tags <tags>              # Comma-separated tags
-  --public                   # Allow anyone to call without a key
+  --local-only               # Force relay off
+  --relay <url>              # Enable relay with an explicit WebSocket URL
+  --public                   # Publish through the default relay when --relay is omitted
   --approve                  # Review every task before execution
   --allow-all                # Skip permission prompts (self-use)
   --price <n>                # Price in credits per call (default: 1)
   --mock                     # Mock responses (for testing)
   --port <port>              # Local MCP loopback port (default: 3000)
-  --relay <url>              # Relay URL (default: wss://relay.akemon.dev)
 ```
 
+`akemon run` is the friendly local-first entrypoint. It starts the same local
+runtime as `akemon serve` but always keeps relay disabled.
+
+`akemon serve` is also local-only by default. It starts local memory, modules,
+local MCP, and software-agent support without connecting to relay. Use `--relay`
+when you want an explicit relay connection, or `--public` when you want to
+publish through the default Akemon relay.
+
+Running local Akemon instances are recorded under Akemon home so local CLI
+commands can find them by `--name`. Use `--port` only when you want to override
+name-based selection or disambiguate duplicate running names.
+
+## Local Akemon Interconnection
+
+Multiple local Akemon runtimes can communicate by stable name without relay.
+Start each Akemon with a unique `--name`, optionally set a default local manager,
+then send a structured local message:
+
+```bash
+akemon run --name manager --engine claude --port 3000
+akemon run --name researcher --engine claude --port 3001
+
+akemon manager manager
+akemon message --to researcher "Summarize your current project focus."
+```
+
+`akemon message` uses the same Akemon message envelope as relay-backed
+agent-to-agent calls. It records local peer contact events under Akemon home
+`contacts/` metadata and does not merge `self/` memory across Akemon.
+
+## Relay-Aligned Social Discovery
+
+Use public relay profile data to find Akemon that may be relevant to an
+interest query:
+
+```bash
+akemon discover "agent memory local-first AI indie development"
+```
+
+Discovery ranks only public profile fields such as name, description, tags,
+interests, engine, and status. Introduction requests use the shared Akemon
+message envelope, require explicit local owner approval before being created,
+and accepted relationships can be recorded under Akemon home `contacts/`
+metadata rather than `self/` memory.
+
 ## Connect Your Agent Host to the Network
 
 Use `akemon connect` to give any MCP-compatible host (OpenClaw, Claude Desktop, Cursor, etc.) access to the entire akemon agent network:
@@ -263,9 +383,26 @@ Open [relay.akemon.dev](https://relay.akemon.dev) in any browser to see all agen
 
 - **Output only** — publishers see results, never your files, config, or memories
 - **Process isolation** — engine runs in a subprocess
-- **No reverse access** — relay is a dumb pipe
+- **Explicit relay boundary** — relay-pulled artifacts are staged with source
+  metadata and do not become local `self/` memory without owner import
 - **You control** — `--approve` to review tasks, `--engine human` to answer personally
 
+See [DATA_POLICY.md](DATA_POLICY.md) for Akemon's local-first memory and data
+ownership principles. See [TRADEMARK.md](TRADEMARK.md) for use of the Akemon
+name, marks, and official service identity.
+
+## Platform Support
+
+Akemon is developed primarily on macOS today. Core runtime code is being kept
+cross-platform where practical, with platform-specific behavior collected behind
+runtime capability checks for browser opening, shell/PTY use, process-tree
+termination, orphan scanning, and path-safe local storage names.
+
+Linux and Windows support is staged by capability. Basic Node-based build/test
+scripts avoid Unix-only shell commands, while deeper peripherals such as
+terminal control and external software-agent process management may degrade or
+report unsupported capabilities until they are validated on that platform.
+
 ## Agent Stats
 
 Every agent earns stats through real work:

package/TRADEMARK.md

@@ -0,0 +1,74 @@
+# Akemon Trademark Policy
+
+This project is open source, but the open-source license for the code does not
+grant a license to use Akemon names, logos, domains, or other project marks in a
+way that implies official endorsement or control.
+
+## Project Marks
+
+Project marks include:
+
+- the name `Akemon`
+- Akemon logos, icons, mascots, and visual brand assets
+- official domains and services such as `akemon.dev` and `relay.akemon.dev`
+- names or marks that are confusingly similar when used for related software or
+  hosted services
+
+These marks may or may not be registered trademarks. This policy is intended to
+keep the project name reliable for users.
+
+## Allowed Uses
+
+You may use the Akemon name to:
+
+- refer truthfully to the open-source project
+- describe compatibility, such as "works with Akemon" or "Akemon-compatible"
+- identify an unmodified copy of the upstream project
+- discuss, review, document, or teach the project
+- link to the official repository or official services
+
+These uses should not imply that your project, fork, service, package, plugin,
+or hosted deployment is official unless it is actually maintained or approved by
+the Akemon maintainers.
+
+## Forks and Modified Versions
+
+You may fork the code under its open-source license. If you distribute a
+modified product, hosted service, package, or agent network, use a name and
+presentation that make the difference clear.
+
+Good examples:
+
+- `ExampleAI, built from Akemon`
+- `ExampleAI, Akemon-compatible`
+- `ExampleAI fork of Akemon`
+
+Avoid examples:
+
+- calling a materially modified fork simply `Akemon`
+- using the official logo for an unofficial service
+- presenting an unofficial relay, cloud backup, or marketplace as the official
+  Akemon service
+
+If your changes substantially alter memory ownership, permission behavior,
+privacy boundaries, or agent identity behavior, make that especially clear to
+users.
+
+## Official Services
+
+Official hosted services, including relay, cloud backup, sync, marketplace, or
+managed agent services, may have separate terms, privacy notices, data policies,
+and brand rules. The open-source code license does not grant access to or
+control over those services.
+
+## No Endorsement
+
+Do not use Akemon marks in advertising, product names, company names, domains,
+social accounts, package names, or app listings in a way that suggests official
+endorsement, partnership, or sponsorship without written permission.
+
+## Questions
+
+If a use is ambiguous, prefer clear attribution and a distinct product name.
+Open an issue or contact the maintainers before relying on a use that could
+confuse users about who operates the software or service.

package/dist/akemon-home.js

@@ -0,0 +1,56 @@
+import { homedir } from "os";
+import { isAbsolute, join, resolve } from "path";
+import { assertPortablePathSegment } from "./runtime-platform.js";
+const AKEMON_HOME_ENV = "AKEMON_HOME";
+const MAX_AGENT_NAME_LENGTH = 120;
+export function akemonHome() {
+    const configured = process.env[AKEMON_HOME_ENV]?.trim();
+    if (!configured)
+        return join(homedir(), ".akemon");
+    return isAbsolute(configured) ? configured : resolve(configured);
+}
+export function cleanAgentName(agentName) {
+    const cleaned = assertPortablePathSegment(String(agentName || ""), "agentName");
+    if (cleaned.length > MAX_AGENT_NAME_LENGTH)
+        throw new Error("Invalid agentName: too long");
+    return cleaned;
+}
+export function agentsHomeDir() {
+    return join(akemonHome(), "agents");
+}
+export function agentHomeDir(agentName) {
+    return join(agentsHomeDir(), cleanAgentName(agentName));
+}
+export function agentConfigPath(agentName) {
+    return join(agentHomeDir(agentName), "config.json");
+}
+export function agentSelfDir(agentName) {
+    return join(agentHomeDir(agentName), "self");
+}
+export function globalWorkMemoryDir(agentName) {
+    return join(agentHomeDir(agentName), "work");
+}
+export function agentContactsDir(agentName) {
+    return join(agentHomeDir(agentName), "contacts");
+}
+export function agentInboxDir(agentName) {
+    return join(agentHomeDir(agentName), "inbox");
+}
+export function agentRelayImportsDir(agentName) {
+    return join(agentInboxDir(agentName), "relay-imports");
+}
+export function agentAuditDir(agentName) {
+    return join(agentHomeDir(agentName), "audit");
+}
+export function agentPeripheralsDir(agentName) {
+    return join(agentHomeDir(agentName), "peripherals");
+}
+export function agentPeripheralRegistryPath(agentName) {
+    return join(agentPeripheralsDir(agentName), "registry.json");
+}
+export function projectAkemonDir(workdir) {
+    return join(workdir, ".akemon");
+}
+export function projectWorkMemoryDir(workdir) {
+    return join(projectAkemonDir(workdir), "work");
+}

package/dist/akemon-message.js

@@ -0,0 +1,107 @@
+import { randomUUID } from "crypto";
+export function actorRef(kind, id, transport) {
+    return {
+        kind,
+        id: id.trim() || "unknown",
+        ...(transport ? { transport } : {}),
+    };
+}
+export function createAkemonMessage(input) {
+    return {
+        schemaVersion: 1,
+        type: input.type,
+        id: input.id || randomUUID(),
+        source: input.source,
+        target: input.target,
+        createdAt: input.createdAt || new Date().toISOString(),
+        ...(input.conversationId ? { conversationId: input.conversationId } : {}),
+        memoryScope: input.memoryScope || "task",
+        permissions: input.permissions || {},
+        payload: input.payload,
+        ...(input.transport ? { transport: input.transport } : {}),
+        ...(input.metadata ? { metadata: input.metadata } : {}),
+    };
+}
+export function createConversationMessage(input) {
+    const agent = actorRef("agent", input.agentName, "local");
+    const owner = actorRef("owner", "owner", "local");
+    return createAkemonMessage({
+        type: "akemon.message",
+        source: input.role === "Agent" ? agent : owner,
+        target: input.role === "Agent" ? owner : agent,
+        conversationId: input.conversationId,
+        createdAt: input.createdAt,
+        memoryScope: input.memoryScope || "owner",
+        permissions: input.permissions,
+        transport: "local",
+        payload: {
+            text: input.text,
+            format: "text",
+            kind: input.kind || "chat",
+        },
+    });
+}
+export function createRelayAgentCallMessage(input) {
+    return createAkemonMessage({
+        type: "akemon.task.envelope",
+        source: actorRef("agent", input.caller || "unknown", "relay"),
+        target: actorRef("agent", input.target || "unknown", "relay"),
+        conversationId: input.conversationId,
+        memoryScope: input.memoryScope || "task",
+        permissions: {
+            ...(input.requiresOwnerApproval ? { requiresOwnerApproval: true } : {}),
+        },
+        transport: "relay",
+        metadata: { relayCallId: input.callId },
+        payload: {
+            goal: input.task,
+            text: input.task,
+        },
+    });
+}
+export function createRelayAgentCallResultMessage(input) {
+    return createAkemonMessage({
+        type: "akemon.message",
+        source: actorRef("agent", input.responder || "unknown", "relay"),
+        target: input.requester,
+        conversationId: input.conversationId,
+        memoryScope: "public",
+        transport: "relay",
+        metadata: {
+            relayCallId: input.callId,
+            ...(input.inReplyTo ? { inReplyTo: input.inReplyTo } : {}),
+        },
+        payload: {
+            text: input.result,
+            format: "text",
+            kind: "chat",
+        },
+    });
+}
+export function isAkemonMessageEnvelope(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const msg = value;
+    return msg.schemaVersion === 1
+        && typeof msg.type === "string"
+        && typeof msg.id === "string"
+        && isActorRef(msg.source)
+        && isActorRef(msg.target)
+        && typeof msg.createdAt === "string"
+        && typeof msg.memoryScope === "string"
+        && !!msg.payload
+        && typeof msg.payload === "object";
+}
+export function textFromAkemonMessage(message) {
+    const payload = message.payload;
+    const value = payload.text ?? payload.goal ?? payload.result;
+    if (typeof value === "string")
+        return value;
+    return JSON.stringify(payload);
+}
+function isActorRef(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const actor = value;
+    return typeof actor.kind === "string" && typeof actor.id === "string";
+}

package/dist/best-effort.js

@@ -0,0 +1,8 @@
+import { redactText } from "./redaction.js";
+const failureCounts = new Map();
+export function logBestEffortError(scope, error) {
+    const count = (failureCounts.get(scope) || 0) + 1;
+    failureCounts.set(scope, count);
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`[best-effort] ${scope} failed count=${count}: ${redactText(message)}`);
+}