@scotthuang/agent-knock-knock 0.13.18 → 0.14.0

package/connectors/deepseek-harness/README.md

@@ -0,0 +1,406 @@
+# Agent Knock Knock for DeepSeek Harness
+
+This package is the native DeepSeek Harness Web connector for Agent Knock
+Knock (AKK). When the Web Host mounts the bundle, it adds `/akk`, the AKK
+semantic tools supplied by its pinned runtime, and the bundled
+`agent-knock-knock` skill to every live Agent.
+There is no `/akk-bind` step, separate skill installation, or session id for
+the user to copy.
+
+The connector is developed in the AKK repository but is an independent npm
+package. It does not modify DeepSeek Harness and has its own version, build,
+tests, lockfile, bundle manifest, and connector-specific release tag.
+
+## Compatibility
+
+This connector pins AKK **0.13.3** in its package and lockfile. Its terminal
+workflow is separate from the AKK 0.14.0 CLI direct, Desktop, and Recovery
+features in the [root README](../../README.md). Neither a newer core release
+nor a root checkout replaces the connector's pinned runtime automatically.
+
+This prerelease supports DeepSeek Harness `0.1.1-rc.2`, `0.1.2-alpha.1`, and
+`0.1.5-rc.2` on the resident Web Host and Node.js `>=22.19.0`. Activation locates the real
+`@deepseek-ai/dsh` launcher and requires that launcher plus its `dsh-base`,
+`dsh-agent`, `dsh-commands`, `dsh-llm`, and `dsh-tools` packages to form one
+coherent set at one reviewed version. An unsupported, missing, or split Host
+fails before mounting. The detected launcher version is also projected into the
+private AKK Host Profile instead of being replaced with a connector build-time
+version. Runtime message and schema helpers are imported from that verified
+Host package tree, so a source checkout's development dependencies cannot
+replace them.
+
+Headless/one-shot Harness processes, Host-exit callback continuity, and Windows
+named pipes are not supported in this release. AKK discovers existing Codex and
+Claude Code processes in tmux or Herdr; this connector does not start those
+processes or create terminal panes.
+
+## Five-minute quick start
+
+### 1. Check the prerequisites
+
+The Web Host must be one of the supported DeepSeek Harness releases, Node
+must satisfy the engine above, and `pnpm` must be on `PATH` because `dsh plugin`
+forwards package operations to pnpm.
+
+```sh
+node --version
+dsh --version
+pnpm --version
+npm view @scotthuang/agent-knock-knock-deepseek-harness dist-tags --json
+```
+
+The last command reports registry state; this repository does not assume that a
+particular prerelease is present in every configured npm registry. Connector
+prereleases use the `next` tag when published.
+
+### 2. Add the connector to the Web profile
+
+```sh
+dsh plugin --profile web add @scotthuang/agent-knock-knock-deepseek-harness@next
+```
+
+Stop the current Web Host cleanly if it is running, then start a fresh process
+so the new bundle is mounted:
+
+```sh
+dsh web
+```
+
+Do not start a second Web Host merely to reload the connector. The callback
+route belongs to the Host process and exact Agent that accepted the command or
+tool invocation.
+
+### 3. Verify discovery in a Web conversation
+
+Make sure at least one Codex or Claude Code process is already running inside a
+tmux or Herdr pane, then enter:
+
+```text
+/akk list
+```
+
+The compact result contains that live terminal, current action names, and only
+the dynamic inputs needed for those actions. Static action meanings and safety
+rules come from the automatically registered `agent-knock-knock` skill. AKK
+never asks callers to invent identifiers: copy only the complete
+`terminal_id`, `session_id`, `turn_id`, `watch_id`, or `native_thread_id`
+returned by AKK.
+
+### 4. Send one task and receive its callback
+
+If exactly one matching terminal is send-ready, this is a complete smoke test:
+
+```text
+/akk codex: Inspect package.json and report the package name. Do not modify files.
+```
+
+Use `claude:` instead when testing Claude Code. With multiple matching panes,
+run `/akk list` first and use the displayed session selector, or let the Agent
+call `agent_knock_knock_send` with the exact semantic identifier in that row's
+advertised action.
+
+An accepted managed Send creates a `turn_id`. When the coding agent finishes,
+asks a question, becomes blocked, or requests approval, AKK sends a callback to
+the same live DeepSeek Harness Agent. A running Agent receives the update via
+`inject()`; an idle Agent receives it via `followup()`.
+
+If stale or broken AKK management prevents managed delivery before terminal
+input, an explicit user Send can instead be delivered once through the physical
+terminal and best-effort attach a Terminal Watch. That result has no managed
+callback Turn; retain its returned `watch_id` for callback recovery. A warning
+that Watch attachment failed does not undo an already successful Send.
+
+### 5. Observe work that AKK did not send
+
+Terminal Watch is read-only and can follow an existing human-started task
+without creating an AKK Session or Turn:
+
+```text
+/akk list
+/akk watch <complete-terminal-id-from-list>
+/akk status <watch-id-returned-by-watch>
+/akk unwatch <watch-id-returned-by-watch>
+```
+
+Watch prefers an exact task anchor and otherwise degrades to warning-bearing
+terminal activity observation. A fallback Watch can prove stable idle, not that
+one uniquely identified task produced the final output.
+
+## Tool workflow
+
+The slash command is the human-facing shortcut. Agents receive the same
+behavior through the complete capability-handshake-verified tool catalog:
+
+| Tool | Purpose |
+| --- | --- |
+| `agent_knock_knock_list` | List live Codex/Claude terminals, managed state, Terminal Watches, and each row's currently available actions. |
+| `agent_knock_knock_watch` | Start durable, read-only observation of one exact `terminal_id`. |
+| `agent_knock_knock_unwatch` | Stop one exact `watch_id` without sending terminal input. |
+| `agent_knock_knock_list_resumable_threads` | List structurally verified native threads for one terminal. |
+| `agent_knock_knock_native_inspect` | Run only the adapter-owned native `status` inspection advertised for an idle terminal. |
+| `agent_knock_knock_model_options` | Read one exact idle terminal's native model and reasoning catalog and create a single-use typed offer. |
+| `agent_knock_knock_repair_model_control` | Dismiss only an exactly recognized stale model-control surface; it never selects a model or submits work. |
+| `agent_knock_knock_set_model` | Consume the current catalog offer to choose one advertised semantic model and reasoning effort. |
+| `agent_knock_knock_identify_foreground` | Run a bounded diagnostic native identity probe without creating durable authority. |
+| `agent_knock_knock_identify_and_send` | Keep one terminal lock across identity observation and one explicit Send when foreground identity is ambiguous. |
+| `agent_knock_knock_new_thread` | Start and verify a clean native coding-agent thread after explicit user intent. |
+| `agent_knock_knock_reconcile_binding` | Detach one proven stale conflicting binding after explicit confirmation; it neither sends work nor adopts a thread. |
+| `agent_knock_knock_resume_thread` | Resume one complete `native_thread_id` from a fresh resumable-thread listing. |
+| `agent_knock_knock_status` | Inspect one AKK `turn_id` or Terminal Watch `watch_id` plus a bounded current screen. |
+| `agent_knock_knock_send` | Send a new task through the exact action advertised by `list`. |
+| `agent_knock_knock_respond` | Answer a question or unblock one existing managed Turn; it does not create a new Turn. |
+| `agent_knock_knock_respond_interaction` | Answer the current typed native questionnaire step for one exact response-capable Turn or Watch. |
+| `agent_knock_knock_approve` | Approve the current exact permission request once, only after human review and confirmation. |
+| `agent_knock_knock_renew` | Renew monitoring for a still-live stalled Turn without typing into the terminal. |
+| `agent_knock_knock_retry_callback` | Retry one persisted failed callback with its original message and delivery identity. |
+| `agent_knock_knock_cancel` | Interrupt one exact active Turn while leaving the shared pane open. |
+| `agent_knock_knock_close` | Release AKK management of a Turn without terminal input, process interruption, or pane closure. |
+
+The ordinary closed loop is:
+
+1. Call `list` and select one exact terminal row.
+2. Use only that row's advertised `send` action and semantic identifier.
+3. Retain the returned `turn_id` for managed delivery, or the `watch_id` from an
+   automatic physical-Send fallback. Completion or attention callbacks return
+   to the originating DeepSeek Harness Agent.
+4. For a managed question or blocked callback, use `respond` with its `turn_id`.
+   For a permission request, follow the approval procedure below.
+5. Use `status` when a callback is late or uncertain. Use an explicit `watch`
+   for other work that was not sent as a managed AKK Turn.
+
+Do not cache `available_actions` or private terminal state. Refresh `list` or
+`status` before a mutation, and never blindly retry an uncertain Send,
+approval, cancel, native inspection, or native thread transition.
+
+## Active approval
+
+The DeepSeek Harness connector registers AKK's approval tool directly; unlike
+the Pi connector, this prerelease does **not** add a Host-native confirm/select
+dialog around that tool. Explicit human confirmation is therefore a required
+calling contract for the Agent and user, not a UI gate enforced by this
+connector. With the default configuration, the manual flow is:
+
+1. Receive the approval callback, then call
+   `agent_knock_knock_status({turn_id})` to refresh the exact current request and
+   terminal screen.
+2. Present the current request, tool name, and relevant arguments to the user.
+3. Obtain an explicit approve or reject decision in the same Web conversation.
+4. Only for an explicit approval, invoke the currently advertised
+   `agent_knock_knock_approve({turn_id})`, or let the user enter
+   `/akk approve <turn-selector>`.
+5. If approval was interrupted or returned an uncertain result, refresh status
+   and let the human inspect the live TUI. Never retry it blindly.
+
+AKK's deterministic `pluginConfig.autoApprove` policy remains disabled by
+default. If an administrator deliberately enables it, only the exact configured
+agent, workspace, and command-vector rules may bypass this manual flow; unmatched
+or ambiguous requests still require the confirmation procedure above.
+
+A separately advertised terminal-scoped approval has no managed `turn_id`.
+Refresh `list`, show that row's current approval request to the user, and after
+explicit confirmation call the advertised `approve` action with its complete
+`terminal_id`. Never convert a terminal-scoped approval into a guessed Turn.
+
+The related controls are deliberately different:
+
+- `respond` supplies text to a question or blocked managed Turn. It is not an
+  approval and is not a generic denial button.
+- `cancel` interrupts the exact active task after explicit user intent. It does
+  not close the pane. A user's rejection must not be silently converted into
+  Cancel; ask separately whether they want the task interrupted or prefer to
+  handle the permission prompt in the live TUI.
+- `close` only releases AKK's management records. It sends no terminal input and
+  does not stop the coding agent; refresh `list` and use `watch` if the process
+  continues working.
+- `unwatch` stops observation only. It never interrupts the watched task.
+
+## Callback delivery and recovery
+
+The synchronous callback acknowledgement means that the message was admitted
+to the exact DeepSeek Harness Agent's inbox/session log. It does not prove that
+the model consumed the message or that asynchronous persistence reached stable
+storage. `status` and Terminal Watch are the recovery path.
+
+- If the exact Agent and Host are still live, inspect the `turn_id` with
+  `status`. A persisted callback failure can be retried with
+  `agent_knock_knock_retry_callback`; AKK reuses the original callback message
+  id and Turn identity for idempotent delivery.
+- For a Terminal Watch, inspect its `watch_id` with `status`. If the route is no
+  longer valid, `unwatch` it and start a fresh Watch from a current `list` row.
+- A Host restart creates a new private Profile revision. Existing watches retain
+  their original route, so callbacks owned by the old Host incarnation fail
+  closed instead of being redirected to a new Agent. There is deliberately no
+  cross-restart callback migration in this prerelease.
+- Replacing an Agent object with another Agent that has the same session id also
+  does not transfer its route. Start a current command/tool invocation from the
+  new Agent before expecting new callback ownership.
+- Exact process-lifetime idempotency records return the original acceptance id
+  for a duplicate callback. Reusing an idempotency key with different content
+  is rejected.
+
+## Configuration
+
+The connector accepts an optional lifecycle cadence and the existing AKK plugin
+configuration object:
+
+```yaml
+- id: agent-knock-knock-deepseek-harness
+  name: '@scotthuang/agent-knock-knock-deepseek-harness'
+  config:
+    lifecycleIntervalMs: 5000
+    pluginConfig:
+      storeDir: /absolute/path/to/akk-store
+```
+
+`lifecycleIntervalMs` must be at least 50 milliseconds. Use an absolute
+`storeDir`; a relative value is resolved from the Web Host's working directory.
+When omitted, AKK uses `~/.agent-knock-knock/store`.
+
+The optional bundle patch mounts only the Host plugin:
+
+```yaml
+- insert:
+    - id: agent-knock-knock-deepseek-harness
+      name: '@scotthuang/agent-knock-knock-deepseek-harness'
+```
+
+## Security and storage
+
+- Each Host process creates a private temporary directory with mode `0700`.
+  Its generated Host Profile is mode `0600`; the directory is removed during a
+  clean connector shutdown.
+- The callback socket path and random token travel only through an allowlisted
+  environment. They are not command arguments. The callback helper uses the
+  absolute Node executable and package artifact without a shell or `PATH`
+  lookup.
+- The callback IPC frame is authenticated and bounded. Successful admission is
+  tied to one exact Agent object and one Host incarnation.
+- AKK's durable Store contains task, Session, Turn, receipt, watch, and callback
+  recovery metadata and may contain user request or callback text. AKK creates
+  Store directories as `0700` and files as `0600`; keep a custom Store on a
+  trusted local filesystem owned by the Host user. Do not share one writable
+  Store between unrelated users.
+- Uninstalling the connector does not delete the durable AKK Store. Retain it if
+  recovery or audit history is still needed; archive or remove it only after
+  confirming there are no active Turns or Watches that depend on it.
+
+## Troubleshooting
+
+| Symptom | Check and recovery |
+| --- | --- |
+| `dsh plugin` cannot run | Confirm `pnpm --version` succeeds. The DeepSeek Harness plugin command forwards its arguments to pnpm. |
+| `@next` cannot be resolved | Run `npm view @scotthuang/agent-knock-knock-deepseek-harness dist-tags --json`. Use an exact published version if your registry has no `next` tag, or use the local-development installation below. |
+| `/akk` and AKK tools are missing | Verify installation with `dsh plugin --profile web why @scotthuang/agent-knock-knock-deepseek-harness`, then fully restart the Web Host. Existing Host processes do not gain a newly added bundle. |
+| Activation reports an unsupported or split Harness | Check `dsh --version` and run `dsh plugin --profile web why @deepseek-ai/dsh-base @deepseek-ai/dsh-agent @deepseek-ai/dsh-commands @deepseek-ai/dsh-llm @deepseek-ai/dsh-tools`. Update the whole Host coherently; do not repair it with a standalone connector npm install. |
+| `/akk list` finds no terminals | Start or locate a real Codex/Claude Code process inside tmux or Herdr. AKK never launches the coding agent or creates its pane. |
+| A mutation is absent or rejected | Refresh `/akk list` or structured `list` and use only the action currently advertised for that exact row. Resolve a current approval first when it blocks input. Do not reuse stale IDs or action payloads. |
+| The callback never appears | Run `/akk status <turn-or-watch-id>`. If the same route is live, use the persisted `retry_callback` tool for a failed Turn callback. After a Host restart or Agent replacement, old delivery fails closed; recreate a Watch or start new work from the current Agent. |
+| Callback delivery reports IPC unavailable or timeout | Keep the originating Web Host alive and inspect whether it was restarted or disposed. The socket is Host-process-private and has an eight-second callback boundary; there is no cross-process fallback route. |
+| A Watch completed but its callback was missed | Query `status` by `watch_id`. Under a new Host incarnation, unwatch the old record and create a fresh Watch from a current terminal row. |
+| A tool call fails schema validation | Pass only the documented fields and complete semantic IDs returned by AKK. DeepSeek's discovery schema is a projection; the connector always enforces the full original AKK schema before execution. |
+| Windows, headless, or one-shot use fails | These surfaces are outside this prerelease's supported scope. Use the resident POSIX Web Host. |
+
+## Upgrade and uninstall
+
+Inspect available versions before changing the profile:
+
+```sh
+npm view @scotthuang/agent-knock-knock-deepseek-harness versions --json
+npm view @scotthuang/agent-knock-knock-deepseek-harness dist-tags --json
+```
+
+Update to the registry's current prerelease, or pin an exact reviewed version:
+
+```sh
+dsh plugin --profile web add @scotthuang/agent-knock-knock-deepseek-harness@next
+dsh plugin --profile web add @scotthuang/agent-knock-knock-deepseek-harness@0.1.0-rc.4
+```
+
+Restart the Web Host after either operation. The connector pins the exact AKK
+runtime version it was tested against, so updating the connector updates that
+tested unit instead of letting the Host Adapter API drift independently.
+
+To uninstall:
+
+```sh
+dsh plugin --profile web remove @scotthuang/agent-knock-knock-deepseek-harness
+```
+
+Restart the Web Host once more. Removal withdraws `/akk`, the tools, and live
+callback routes; it does not delete the durable AKK Store.
+
+## Local development
+
+From the AKK repository root, install and build the child package, then add that
+connector checkout to the Web profile:
+
+```sh
+npm --prefix connectors/deepseek-harness ci
+npm run deepseek:build
+dsh plugin --profile web add "file:$(pwd -P)/connectors/deepseek-harness"
+```
+
+Restart `dsh web` after installation. The child package currently installs and
+tests against its pinned published AKK runtime `0.13.3`; building the current
+repository root does not silently replace that dependency. Testing connector
+changes against another AKK runtime requires an explicit dependency change and
+compatibility review rather than an implicit local link.
+
+## Tests and release status
+
+The package manifest is currently `0.1.0-rc.4`, so this remains a prerelease and
+is published under `next`; `latest` remains on the earlier `0.1.0-rc.1` tag.
+Registry state can change independently of this source file, so the `npm view`
+commands above remain authoritative.
+
+From `connectors/deepseek-harness`, the normal development gate is:
+
+```sh
+npm ci
+npm run typecheck
+npm run test:fast
+npm run pack:check
+```
+
+These commands typecheck the connector, run its fast wiring/profile/IPC/schema
+tests, and inspect the package tarball. They do not publish anything. The
+`0.1.0-rc.4` compatibility work is typechecked against the published DeepSeek
+Harness `0.1.5-rc.2` SDK packages and runtime-smoked against that exact official
+launcher package tree. The reproducible development lock therefore uses
+`0.1.5-rc.2`, while peer and runtime checks retain the two older reviewed Host
+versions for existing installations.
+
+## Release safety
+
+`npm run release:check` is check-only. The shared connector gate first proves
+the generated Skill hash, package manifest/constants/lock/dependency parity,
+then runs typecheck, fast tests, and inspection of the real package tarball. In
+release mode it additionally rejects a dirty tree, a non-`main` branch, an
+unsynchronized upstream, an existing npm version or connector repository tag,
+and any runtime `file:`, `link:`, or `workspace:` dependency.
+
+Activation separately verifies the pinned AKK HostAdapter's versioned,
+secretless capability handshake. The authoritative catalog digest, ordered
+tool names and derived count, and Skill digest must match the generated Skill
+and the tools registered with DeepSeek Harness. A missing/unknown handshake,
+forged digest, or partial registration fails closed; the connector has no
+independent hard-coded tool count.
+
+For deterministic local verification without a registry or git-remote query:
+
+```sh
+npm run release:check -- --offline
+```
+
+From the repository root, `npm run connectors:verify` applies that same offline
+gate to both connectors. Their package versions are validated independently.
+
+Publishing additionally requires both explicit flags:
+
+```sh
+npm run release:check -- --publish --confirm-version 0.1.0-rc.4
+```
+
+Prereleases use npm tag `next`; stable versions use `latest`. Repository tags
+and GitHub Releases use the connector-specific namespace
+`deepseek-harness-v<version>` and are created separately after npm verification.

package/connectors/pi/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agent Knock Knock contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.