@karma42/agent 0.1.0-beta.3 → 0.1.0-beta.4

package/README.md

@@ -1,115 +1,35 @@
-# Karma42 agent — current-session MCP connection
+# Karma42 MCP connector
 
-Version `0.1.0-beta.3` is the browser-pairing candidate. Publication and real-client acceptance are separate release checks. The bundled bridge adds a named connection to your existing Claude Code or Codex conversation; it does not launch another coding model or change client permissions.
+`0.1.0-beta.4` is an **unpublished draft**. It connects an existing MCP-capable AI client to a Karma42 project. It does not select, download or run a model. An MCP-capable client using DeepSeek or another model can use the same transport if that client supports local stdio MCP and the required project tools.
 
-In **My agents**, choose an agent and copy its project-specific instructions. After your setup approval, your agent runs:
+## First-time setup
 
-```sh
-npx --ignore-scripts @karma42/agent@0.1.0-beta.3 browser-connect --project-url HTTPS_SERVICE/p/PROJECT_ID --provider claude --agent-id AGENT_ID
-```
-
-Use `--provider codex` in Codex. The current folder is the requested workspace; `--folder /absolute/workspace` selects another. Setup prints a browser link and request check, then exits immediately. Open the link, sign in with Google, match the request check to this session, and review the project, agent, requested folder and access before approving. The browser does not independently verify that local folder. Approval does not grant filesystem/GitHub permissions, start development or edit client settings. Native client trust prompts remain yours.
-
-Run `browser-prepare --connection ID` after approval. It checks once; if pending it prints the link again without keeping a process or lock open. Approved requests save the credential privately and return the secret-free named MCP entry. Lost HTTP replies and interrupted local saves are recoverable by retrying this same command; do not delete the private receipt or create another request. `browser-status --connection ID` shows local pending/saved metadata only, never online activity. Cancel a pending request in the signed-in browser. Expired/cancelled requests preserve existing saved credentials; repeat `browser-connect` for a fresh request. `browser-connect --reconnect` requests a replacement after a previously saved setup, with browser confirmation required before any active connection is replaced.
-
-The server receives the hash of a locally generated credential, never its plaintext. The polling secret and candidate credential stay in private 0600 files under 0700 directories; neither appears in the URL, command arguments, chat or MCP configuration. Per-project/service/agent locks cover only short local operations and HTTP requests. No lock is held while a human approves in the browser. Recognized browser-operation locks whose PID is confirmed dead recover automatically; live, reused or uncertain PIDs and legacy bridge locks are never stopped or removed. Recovery attempts are serialized and recheck the lock inode/content. An interrupted recovery guard is conservatively refused rather than deleting an uncertain lock. Two different agents/projects can set up independently; duplicate operations for the same identity are refused safely. Pending requests expire on the service; approved receipts remain recoverable.
-
-The deployed beta.2 private-code command remains an identified compatibility path: `session-connect` requires an interactive terminal, rejects pipes/redirected input before taking a lock and never runs in the background. Codes belong only in its private prompt. Expected agent IDs lock only that agent, without a whole-home lock. Existing beta.2 session records remain valid and continue to pin their beta.2 bridge rather than silently upgrading a live connection. OPE-43 owns retirement after participant migration and independent acceptance.
-
-Setup returns a secret-free MCP entry and instructions for the selected client. Ask your current agent to add only that entry after your approval, preserving all other entries. Claude uses its workspace-local `mcp add --scope local` command; Codex uses the trusted workspace’s `.codex/config.toml`. Do not share machine-specific paths in repository config. Native trust and permission prompts remain under your control. The client may need MCP reload before tools appear; return to the existing conversation and verify `get_project` on the named entry before continuing. macOS is the tested package environment; Linux and Windows acceptance remains pending. Independent real-client reload/continuation acceptance is still pending; configuration generation and the actual stdio process are tested separately.
-
-Each service/project/agent combination has its own ID, credentials and MCP name. Local and production services are distinct even when their IDs match. Several catalogs may load without claiming their agents. The first `get_project` call claims only its connection and verifies `you.agentId` and `you.agentName`; other tool calls are refused until this succeeds. Use a separate named agent for concurrent sessions. A second process using one identity is refused without takeover. Workspace scoping is client configuration, not a security sandbox; credentials are scoped by the service to their project agent.
-
-Commands: `session-connect`, `session-prepare --connection ID` (recover interrupted pairing), `session-config --connection ID` (print the secret-free entry), `session-status` (local records only), and `session-serve --connection ID` (stdio transport, started by the MCP client). Session commands use separate private storage at `~/.karma42/sessions/SERVICE_PROJECT_HASH/AGENT_ID`; `--state-dir` selects a private test root. Browser setup records survive interruption. Browser approval explicitly confirms credential replacement; pending/cancelled requests do not rotate it. Legacy private codes rotate that identity’s credential, so disconnect its old bridge/runner before private-code setup. Other identities and their history are preserved.
-
-The client owns the bridge process. EOF or SIGINT/SIGTERM/SIGHUP reports stopping, closes polling and releases the local identity lock. Closing a chat does not necessarily close the client-owned process; explicitly disconnect the named MCP entry to release it. A crash/SIGKILL cannot send a final report: the backend’s existing lease/fencing and stale-lock recovery still apply. No remote kill of the coding client is promised. Catalog discovery and connection contact are not evidence of model work or measured spending. The bridge retains the canonical bounded deferred-send journal/retries, only while connected. Revocation, stale runs, paused/not-started mutations and urgent runtime barriers remain enforced by the service; the bridge never downloads or executes cloud-selected runner updates to bypass a refusal.
-
-The pinned beta.1 foreground-runner path remains for identified existing users. It uses different private storage and is not silently migrated. The commands below describe that legacy path; new onboarding uses the current-session commands above. OPE-12/OPE-43 own migration and eventual retirement after independent acceptance.
-
-## Existing foreground runner
-
-# Karma42 agent — beta release
-
-Version `0.1.0-beta.1`. The package implements connection preparation, permission approval and a separate foreground start using the existing Karma42 agent runtime. This beta is prepared for public npm distribution. Publication status is recorded in the release plan. The deployed website still uses the existing setup instructions.
-
-## The participant flow
-
-1. Join the project in Karma42. In project **My agents**, create an agent or choose Reconnect and obtain its short-lived setup code.
-2. In your terminal, run **connect**, explicitly choosing Claude Code or Codex and guarded or bypass permissions. Local prerequisites are checked before the setup code is consumed. Paste the code into a hidden prompt; it never belongs in a command, environment variable or chat transcript.
-3. Pairing retrieves the authoritative agent identity and repository. Review the repository, local checkout, GitHub account, permissions, model-usage risks and current service-managed update policy. Answer each acknowledgement yourself. Bypass also requires the isolated-environment acknowledgement and typing `BYPASS`.
-4. Preparation clones or validates the checkout, installs the packaged canonical kit, and reports readiness to Karma42. It does **not** start an agent. Git can invoke local hooks/filters while cloning. Model sign-in remains owned by your local coding client.
-5. Run **start** separately. The confirmation shows the provider, saved permissions and newly checked GitHub account. On an active project the model can work immediately and consume usage; while preparing or paused it waits. Keep the terminal open. **Ctrl+C** stops this foreground runner; completed changes and external actions remain.
-6. Use **status** for local preparation/approval/check timestamps. Open **My agents** for service-observed contact and activity. A local lock, missing contact or past readiness check is not proof an agent is currently working or stopped.
-
-Project approval, joining, agent connection and the owner's Start project remain separate actions.
-
-## Build and install locally
-
-Supported package verification: macOS with Node 22+, Git, GitHub CLI and Claude Code 2.1.259+ or Codex CLI 0.160.0+. POSIX paths and private filesystem permissions are required. Linux and independent-operator acceptance remain release checks; Windows is not claimed as supported in this iteration.
-
-From the repository:
-
-```sh
-npm --prefix packages/agent-cli test
-npm pack ./packages/agent-cli --pack-destination /private/tmp
-npm install --global --offline --ignore-scripts --no-audit --no-fund /private/tmp/karma42-agent-0.1.0-beta.1.tgz
-karma42-agent --help
-```
-
-Installation has no preinstall/install/postinstall/prepare hooks, contacts no project service and launches no model. Packaging runs a local build that copies the canonical kit from `pilot/agent-kit`; it does not execute that kit. There are no external package dependencies.
-
-For a real project, replace `PROJECT_ID` and `SERVICE_ORIGIN` with its service URL from My agents:
+Once per computer and client, print its registration instructions:
 
 ```sh
-karma42-agent doctor --provider claude
-karma42-agent connect --project-url https://SERVICE_ORIGIN/p/PROJECT_ID --provider claude --mode guarded
-karma42-agent status
-karma42-agent start --connection PROJECT_ID/AGENT_ID
+npx --ignore-scripts @karma42/agent@0.1.0-beta.4 mcp-config --client claude
 ```
 
-The example placeholders are not runnable projects. Do not use production setup codes for automated tests. Start is an explicit authorization to run the installed provider, subject to project state and current service authorization.
-
-Optional: `--folder /absolute/real/checkout` selects an existing repository root or a new checkout under an existing real directory. Its HTTPS origin must match the project's repository exactly (optional `.git` suffix is normalized). The CLI never resets files, pulls changes or changes the origin. Custom checkouts must be separate from private connection storage, without symbolic-link paths. Existing working files are preserved.
-
-## Commands and recovery
-
-| Command | What it does |
-| --- | --- |
-| `connect --project-url … --provider claude\|codex --mode guarded\|bypass` | Checks versions, privately exchanges a code, records permission approval, prepares checkout and reports readiness. Never starts. |
-| `prepare --connection ID` | Recovers an interrupted pairing or repeats preparation/readiness using the saved credential, without consuming another code. Renews preparation approval. |
-| `start --connection ID` | Validates saved approval, bundle, checkout and current service authorization, refreshes GitHub evidence, asks to start, then runs in the foreground. |
-| `reconnect --connection ID` | Privately exchanges a fresh code for the same agent/repository, rotates its credential and prepares again. Preserves checkout, sessions, logs and recovery files. Stop the previous runner first. |
-| `permissions --connection ID --mode guarded\|bypass [--provider claude\|codex]` | Reviews and records the chosen permissions, refreshes preparation, and leaves the runner stopped. |
-| `status [--connection ID] [--json]` | Lists local records and pending recovery, without contacting the server or claiming online/working state. |
-| `doctor --provider claude\|codex [--json]` | Checks installed versions only. No account, model sign-in or repository-access claim. |
-| `preview --provider … --mode … --project-url … --repo … --folder … [--json]` | Displays unverified onboarding copy with no connection or persisted approval. |
-
-Connection commands accept `--state-dir /absolute/private/directory` for isolated tests or explicit local storage. Repeat the same option on later commands. The default is `~/.karma42/connections`.
-
-An expired/refused code requires a new code in My agents. After a lost exchange response, its consumption is uncertain: do not blindly retry; generate a fresh code. After a successful response, an interrupted local application leaves a private receipt that `prepare` can recover. `status` identifies pending preparation. A mismatched reconnect never overwrites the previous identity or checkout; review the indicated connection separately. Repository identity changes are refused rather than silently authorized.
-
-If GitHub access is unconfirmed, preparation reports **action required**. Sign in with `gh`, ask the owner for repository access and accept the invitation, then rerun `prepare`. Start requires an additional warning acknowledgement if write access remains unconfirmed; this preserves the existing warning behavior while the broader blocking policy remains undecided.
-
-A lock prevents simultaneous package operations. After an unexpected kill, inspect the PID in `operation.lock` and confirm that the process has stopped before removing that lock. There is no automatic takeover or background service. Use the same `start` command to return after a normal stop.
+Use `--client codex` for Codex, or `--client other` for the generic stdio configuration. **Client selection changes the configuration format; it does not choose your model.** These npm commands become available after publication; source-draft testing uses the locally built package.
 
-Service revocation remains in the authenticated website. It blocks future authorized service work but is not a guaranteed remote kill of local OS processes. This package does not invent a local-only “disconnect” that claims service revocation.
+Review and approve adding the single **karma42** connection. Claude Code uses user scope; Codex uses user configuration. Other clients receive a JSON command/arguments entry to adapt to their configuration schema. Inspect an existing `karma42` entry before changing it, and preserve other connections and native permissions. This command prints instructions only and makes no settings changes.
 
-## Permissions and runtime updates
+Start a project conversation with the connector loaded and approve any native trust prompt. First-time installation may require a client reload. Merely printing or saving configuration does not verify that its tools loaded.
 
-Guarded Claude uses the canonical `acceptEdits` mode and configured tools, with no interactive action prompts. Requests needing extra permission are refused. These rules are not an OS sandbox: project scripts and Git hooks can access what your OS account can access. Guarded Codex uses workspace-write and automatic approval review; approved escalations may run outside that sandbox. Neither mode means human approval for every action.
+References: [Claude Code MCP setup](https://code.claude.com/docs/en/mcp-quickstart), [official OpenAI MCP documentation](https://developers.openai.com/codex/mcp).
 
-Bypass Claude skips normal permission checks; bypass Codex disables the sandbox and approval review. Use an appropriate isolated or disposable environment. A checkout folder alone does not isolate the machine. The package never selects bypass implicitly, adds global allow rules, accepts native trust prompts for you, or edits personal client configuration.
+## Project-agent onboarding
 
-Saved preparation consent is bound to the project service, agent identity, repository, absolute folder, provider, permission mode, copy version, packaged baseline and runtime policy. Changed/stale records or modified baseline files require preparation before start. Every start has its own explicit confirmation. Shell `PILOT_*` variables are filtered before the supervisor launches, so old bypass, tools, takeover or environment-passthrough overrides do not silently expand access. Provider authentication remains local.
+Copy the project-agent instructions from [Karma42](https://karma42.ai) into the conversation. Approve connecting the named agent in its project and working folder. The agent calls `connect_project_agent`, shows a short browser approval link and request check, then waits for you to approve it in Karma42. Review the project, agent and requested folder; the browser cannot independently verify that folder.
 
-The package bundles the **single canonical runtime** from `pilot/agent-kit`, with an integrity manifest. It retains the existing supervisor's service-selected compatible runtime/instruction updates and discloses that before approval. Hash checks are not publisher signatures; runtime signing and OS isolation retain their existing separate scopes. Installing a new npm package is manual; changed package baselines require renewed preparation. No default turn/time/spending caps are introduced.
+After approval, `finish_project_agent_connection` uses the returned connection_ref to finish binding. `get_project` with that reference verifies identity and reads context. Keep the same reference on every subsequent project tool call. Connecting does not authorize development, messages, GitHub changes or broader permissions. Your client controls those actions and model usage.
 
-## Storage, migration and verification
+The connector supports separate processes and hosts that share one MCP process across conversations. Each agent/project has an immutable binding with an opaque connection_ref. Every project tool requires this exact reference; there is no global active project or default target. Different bindings can work concurrently. Duplicate active identities retain exclusive run fences without automatic takeover. An explicitly selected approved connection can be reused for its matching identity and reported folder.
 
-Private records live at `~/.karma42/connections/PROJECT_ID/AGENT_ID/`. Runtime state, token, sessions, logs and releases live under `agent-state/AGENT_NAME/`; the default checkout is the separate sibling `workspace/`. Directories use 0700, credential/record files 0600. The CLI refuses unsafe permissions, symbolic links and malformed records without echoing private input.
+## Transport and private state
 
-Legacy `~/.agent-projects` helpers/launchers remain identified active consumers. This package does not import, alter, delete or start them. Reconnecting a chosen identity intentionally rotates its server token; stop its old runner first. OPE-12/OPE-43 own replacement of the website instructions and retirement after independent acceptance and explicit participant migration.
+The client runs `mcp-serve`, which serves JSON-RPC over stdin/stdout without launching a model or background service. Node 22+ is required. `disconnect_project_agent` releases only the specified binding; EOF or transport termination releases all bindings in that process; completed external actions are not undone. Run fences, membership, revocation and project-state checks remain enforced by the service.
 
-Focused tests cover preparation/start separation, all provider/mode choices, cancelled acknowledgements, expired/refused responses, interrupted pairing, clone/readiness failures, wrong origin, credential privacy, stale consent, concurrent operations, reconnect preservation, pending recovery, GitHub account visibility, naming/path collisions and environment filtering. The foreground stop test uses the real supervisor with a disposable **stub runner**, not a model. An installed-artifact terminal rehearsal uses synthetic service responses and local tool fixtures. No production credentials, persistent emulator reset, real GitHub mutation or model execution is part of these tests.
+Private records use `~/.karma42/mcp` or `--state-dir /absolute/private/directory`. Storage must be private and outside the working folder. Credentials and polling secrets remain in private files; never put them in chat, arguments, URLs or client configuration. Pending browser approvals can be resumed; cancellation or expiry preserves an existing credential. Replacement requires explicit browser approval.
 
-Browser-pairing website activation, signed runtime releases, independent operator/real-model acceptance and deployment remain separate release steps. This beta does not claim independent real-model acceptance. See `docs/onboarding/agent-connection-plan.md` for the product flow and release gates.
+This source contains only the current MCP connector. Old npm releases remain published independently; this cleanup neither migrates their private records nor deletes production data or interrupts existing sessions. Native client and operating-system acceptance remain separate release checks. Configuration and protocol tests do not establish that every MCP client supports dynamic setup, reload or continuation.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@karma42/agent",
-  "version": "0.1.0-beta.3",
-  "description": "Karma42 named project MCP connections for your current coding session",
+  "version": "0.1.0-beta.4",
+  "description": "Model-independent Karma42 MCP connector for project agents",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
@@ -30,5 +30,6 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public",
     "tag": "beta"
-  }
+  },
+  "homepage": "https://karma42.ai"
 }

package/runtime/manifest.json

@@ -1,12 +1,7 @@
 {
   "source": "pilot/agent-kit",
   "files": {
-    "runner.mjs": "984d2eabc54f2561397a04c851c29f8362d83e9521063222c2a3ce2725e3e06f",
     "control-v2.mjs": "02e325b642669b8f29c7b25582b1afaf4b74cbc63d2b463c11bf02abac90ca12",
-    "runtime.mjs": "bceb586f369ca373f919ab848ace6968518d15c49057798778c6bfed3e76d8fc",
-    "launcher.mjs": "4254a649e02597f21b5f3c1b146490554a19cc9919933a3dfdc55113cbf140aa",
-    "claude-settings.json": "bf3bfaaf38de37cda60a7dc48cb8c186c1864df61bd5ff500715ee2d1db4333e",
-    "AGENT_PROMPT_V2.md": "1a4f28e8105db39d384b63ef32cf06a9b14057da2e12fd2d0a0c0f3f1ca02d80",
-    "providers.mjs": "90e70acd1d2363f28584c8ccbc5cce7f9851c4aae1864309ff408822050a10ef"
+    "project-tools.json": "e0b97987df7887bb10926651de61cf886d6fd19b774ee1ecf3a67241e5cc98bd"
   }
 }