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

package/README.md

@@ -1,103 +1,35 @@
-# Karma42 agent — current-session MCP connection
+# Karma42 MCP connector
 
-Version `0.1.0-beta.2` adds a named project connection to your existing Claude Code or Codex conversation. The npm package bundles the local MCP bridge. It does not launch a coding model or change client approval/sandbox settings.
+`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.
 
-Get the project-specific prompt and a private code in **My agents**. Paste the prompt into your current agent conversation. Run `session-connect --project-url HTTPS_SERVICE/p/PROJECT_ID --provider claude|codex --agent-id AGENT_ID` in the current workspace; supply the code privately when prompted, never in arguments or chat. Review the authoritative project, repository, agent and workspace before saving. This setup does not check GitHub access, clone a repository or record model authentication as verified.
+## First-time setup
 
-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. A saved pairing receipt survives cancellation. New setup codes rotate that identity’s service credential, so disconnect its old bridge/runner first. 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:
+Once per computer and client, print its registration instructions:
 
 ```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
+npx --ignore-scripts @karma42/agent@0.1.0-beta.4 mcp-config --client claude
 ```
 
-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:
-
-```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
-```
-
-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 OAuth 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.2",
-  "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"
   }
 }