nextclaw 0.19.24 → 0.19.27

package/dist/cli/launcher/index.js

@@ -6,3 +6,5 @@ NextclawDistributionService.configure(createNextclawDistribution(import.meta.url
 runNextclawNpmRuntimeLauncher(process.argv);
 //#endregion
 export {};
+
+//# sourceMappingURL=index.js.map

package/dist/cli/launcher/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/cli/launcher/index.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { NextclawDistributionService, runNextclawNpmRuntimeLauncher } from \"@nextclaw/service\";\nimport { createNextclawDistribution } from \"@nextclaw-cli/cli/shared/lib/distribution/index.js\";\n\nNextclawDistributionService.configure(createNextclawDistribution(import.meta.url));\nrunNextclawNpmRuntimeLauncher(process.argv);\n"],"mappings":";;;;AAIA,4BAA4B,UAAU,2BAA2B,OAAO,KAAK,IAAI,CAAC;AAClF,8BAA8B,QAAQ,KAAK"}

package/dist/nextclaw-distribution.utils-BJZhAnGk.js

@@ -15,3 +15,5 @@ function createNextclawDistribution(importMetaUrl) {
 }
 //#endregion
 export { createNextclawDistribution as t };
+
+//# sourceMappingURL=nextclaw-distribution.utils-BJZhAnGk.js.map

package/dist/nextclaw-distribution.utils-BJZhAnGk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nextclaw-distribution.utils-BJZhAnGk.js","names":[],"sources":["../src/cli/shared/lib/distribution/nextclaw-distribution.utils.ts"],"sourcesContent":["import { readFileSync } from \"node:fs\";\nimport { dirname, resolve } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport type { NextclawDistribution } from \"@nextclaw/service\";\n\nexport function createNextclawDistribution(importMetaUrl: string): NextclawDistribution {\n  const packageRoot = resolve(dirname(fileURLToPath(importMetaUrl)), \"../../..\");\n  const { version } = JSON.parse(readFileSync(resolve(packageRoot, \"package.json\"), \"utf-8\")) as { version?: string };\n  return {\n    version: typeof version === \"string\" ? version : \"0.0.0\",\n    packageRoot,\n    appEntrypoint: resolve(packageRoot, \"dist/cli/app/index.js\"),\n    uiDistDir: resolve(packageRoot, \"ui-dist\"),\n    runtimeUpdatePublicKeyPath: resolve(packageRoot, \"resources/update-bundle-public.pem\")\n  };\n}\n"],"mappings":";;;;AAKA,SAAgB,2BAA2B,eAA6C;CACtF,MAAM,cAAc,QAAQ,QAAQ,cAAc,cAAc,CAAC,EAAE,WAAW;CAC9E,MAAM,EAAE,YAAY,KAAK,MAAM,aAAa,QAAQ,aAAa,eAAe,EAAE,QAAQ,CAAC;AAC3F,QAAO;EACL,SAAS,OAAO,YAAY,WAAW,UAAU;EACjD;EACA,eAAe,QAAQ,aAAa,wBAAwB;EAC5D,WAAW,QAAQ,aAAa,UAAU;EAC1C,4BAA4B,QAAQ,aAAa,qCAAqC;EACvF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nextclaw",
-  "version": "0.19.24",
+  "version": "0.19.27",
   "description": "Lightweight personal AI assistant with CLI, multi-provider routing, and channel integrations.",
   "private": false,
   "type": "module",
@@ -41,21 +41,21 @@
     "commander": "^12.1.0",
     "jszip": "^3.10.1",
     "yaml": "^2.8.1",
-    "@nextclaw/core": "0.12.21",
-    "@nextclaw/kernel": "0.1.11",
-    "@nextclaw/mcp": "0.1.86",
-    "@nextclaw/ncp": "0.5.14",
-    "@nextclaw/ncp-agent-runtime": "0.3.25",
-    "@nextclaw/ncp-mcp": "0.1.88",
-    "@nextclaw/ncp-toolkit": "0.5.19",
-    "@nextclaw/nextclaw-hermes-acp-bridge": "0.1.13",
-    "@nextclaw/nextclaw-ncp-runtime-http-client": "0.1.13",
-    "@nextclaw/nextclaw-ncp-runtime-stdio-client": "0.1.14",
-    "@nextclaw/openclaw-compat": "1.0.21",
-    "@nextclaw/remote": "0.1.99",
-    "@nextclaw/runtime": "0.2.53",
-    "@nextclaw/service": "0.1.14",
-    "@nextclaw/server": "0.12.22"
+    "@nextclaw/core": "0.12.23",
+    "@nextclaw/ncp-agent-runtime": "0.3.27",
+    "@nextclaw/ncp-mcp": "0.1.90",
+    "@nextclaw/ncp-toolkit": "0.5.21",
+    "@nextclaw/nextclaw-ncp-runtime-http-client": "0.1.15",
+    "@nextclaw/nextclaw-hermes-acp-bridge": "0.1.15",
+    "@nextclaw/openclaw-compat": "1.0.23",
+    "@nextclaw/nextclaw-ncp-runtime-stdio-client": "0.1.16",
+    "@nextclaw/ncp": "0.5.16",
+    "@nextclaw/service": "0.1.16",
+    "@nextclaw/server": "0.12.24",
+    "@nextclaw/runtime": "0.2.55",
+    "@nextclaw/kernel": "0.1.13",
+    "@nextclaw/mcp": "0.1.88",
+    "@nextclaw/remote": "0.1.101"
   },
   "devDependencies": {
     "@types/node": "^20.17.6",
@@ -63,12 +63,12 @@
     "tsx": "^4.19.2",
     "typescript": "^5.6.3",
     "vitest": "^4.1.2",
-    "@nextclaw/ui": "0.12.31"
+    "@nextclaw/ui": "0.12.33"
   },
   "scripts": {
-    "dev": "tsx watch --tsconfig tsconfig.json src/cli/app/index.ts",
-    "dev:build": "tsx src/cli/app/index.ts",
-    "build": "node scripts/sync-usage-resource.mjs && tsdown src/index.ts src/cli/app/index.ts src/cli/launcher/index.ts --dts --clean --target es2022 --no-fixedExtension && node scripts/copy-ui-dist.mjs",
+    "dev": "tsx watch --tsconfig ../../scripts/dev/dev-runtime.tsconfig.json src/cli/app/index.ts",
+    "dev:build": "tsx --tsconfig ../../scripts/dev/dev-runtime.tsconfig.json src/cli/app/index.ts",
+    "build": "node scripts/sync-usage-resource.mjs && tsdown src/index.ts src/cli/app/index.ts src/cli/launcher/index.ts --dts.sourcemap --clean --target es2022 --no-fixedExtension && node scripts/copy-ui-dist.mjs",
     "runtime-update:build": "node scripts/build-npm-runtime-update-channel.mjs",
     "smoke:npm-runtime-update": "node scripts/smoke-npm-runtime-update.mjs",
     "validation:npm-update": "node scripts/smoke-npm-runtime-update.mjs --manual",

package/resources/USAGE.md

@@ -13,9 +13,11 @@ When NextClaw AI needs to operate the product itself (version/status/doctor/serv
 1. **Read the built-in self-management guide first**. The packaged runtime copy lives at `packages/nextclaw/resources/USAGE.md`, and this repo page is kept aligned with it.
 2. **Use the exact command for the intent**: use `nextclaw --version` for version lookup; do not infer version from `status`.
 3. **Prefer machine-readable output** (`--json`) whenever available.
-4. **Close the loop after changes** with `nextclaw status --json` (and `nextclaw doctor --json` when needed).
-5. **Be explicit about restart semantics** (hot-apply, auto-restart, or manual restart required).
-6. **Never invent commands**; use documented commands or `nextclaw --help` / `nextclaw <subcommand> --help`.
+4. **Discover runtime HTTP addresses from `nextclaw status --json`** before calling local APIs or `/webhook`; use `endpoints.uiUrl` and `endpoints.apiUrl` instead of guessing ports.
+5. **Close the loop after changes** with `nextclaw status --json` (and `nextclaw doctor --json` when needed).
+6. **Be explicit about restart semantics** (hot-apply, auto-restart, or manual restart required).
+7. **Never invent commands**; use documented commands or `nextclaw --help` / `nextclaw <subcommand> --help`.
+8. **Desktop-installed AI uses the same command names**. When NextClaw Desktop launches the runtime, it exposes a managed `nextclaw` command surface to AI command tools, so self-management commands keep using `nextclaw ...` without requiring a global NPM install.
 
 ---
 
@@ -24,6 +26,7 @@ When NextClaw AI needs to operate the product itself (version/status/doctor/serv
 - [AI Self-Management Contract](#ai-self-management-contract)
 - [Quick Start](#quick-start)
 - [Public Server Deployment](#public-server-deployment)
+- [HTTP Webhook Ingress](#http-webhook-ingress)
 - [Configuration](#configuration)
 - [Input context budget](#input-context-budget)
 - [Multi-agent routing & session isolation](#multi-agent-routing--session-isolation-openclaw-aligned)
@@ -121,6 +124,53 @@ If `127.0.0.1:55667` is healthy but the public entry returns `502`, the problem
 
 ---
 
+## HTTP Webhook Ingress
+
+NextClaw exposes a generic webhook ingress for external systems and small local tools that need to trigger NextClaw work:
+
+```text
+POST /webhook
+```
+
+This section is intentionally only an index. Read the focused guide only when you need to implement or debug a webhook caller:
+
+- [HTTP webhook ingress guide](usage/http-webhook-ingress.md)
+
+For AI or scripts, do not guess the port. Discover the running service first:
+
+```bash
+nextclaw status --json
+```
+
+Read these fields:
+
+- `endpoints.uiUrl`: base URL for UI and `/webhook`, for example `http://127.0.0.1:55667`.
+- `endpoints.apiUrl`: base URL for API routes, for example `http://127.0.0.1:55667/api`.
+- `remote.runtime.localOrigin`: local origin used by the service-managed remote connector when remote access is enabled.
+
+Then call:
+
+```text
+<endpoints.uiUrl>/webhook
+```
+
+Current third-party trigger entry:
+
+```json
+{
+  "type": "agent-run.send",
+  "payload": {
+    "content": [
+      { "type": "text", "text": "Reply exactly: Webhook smoke received" }
+    ]
+  }
+}
+```
+
+Unknown ingress types are rejected instead of being turned into chat messages. Use the focused guide for full payload fields, existing-session calls, verification, and error semantics.
+
+---
+
 ## Configuration
 
 - **Config file:** `~/.nextclaw/config.json`
@@ -653,6 +703,7 @@ Status/diagnostics tips:
 - `nextclaw --version` is the only supported way to query the installed CLI version.
 - `nextclaw status` shows runtime truth (process + health + config summary).
 - `nextclaw status --json` outputs machine-readable status and exits `0` when the command itself succeeds; use the JSON `level` field (`healthy` / `degraded` / `stopped`) to interpret runtime state.
+- Use `nextclaw status --json` as the source of truth for local HTTP addresses. `endpoints.uiUrl` is the base for `/webhook`; `endpoints.apiUrl` is the base for `/api/*` calls.
 - `nextclaw status --fix` safely clears stale service state if PID is dead.
 - `nextclaw doctor` runs additional checks (state coherence, health, port availability, provider readiness).
 - `nextclaw usage` shows the latest observed LLM usage snapshot from recent CLI agent runs or the local UI/NCP runtime.

package/resources/usage/http-webhook-ingress.md

@@ -0,0 +1,145 @@
+<!-- Generated by packages/nextclaw/scripts/sync-usage-resource.mjs -->
+<!-- Do not edit this file directly; edit docs/usage/http-webhook-ingress.md instead. -->
+# HTTP Webhook Ingress
+
+This focused guide is for developers, local scripts, and AI agents that need to call NextClaw's HTTP webhook ingress.
+
+## Endpoint
+
+NextClaw exposes a generic webhook ingress at:
+
+```text
+POST /webhook
+```
+
+Use the same host and port as the running gateway/UI:
+
+- packaged service default: `http://127.0.0.1:55667/webhook`
+- local repo dev default: `http://127.0.0.1:18792/webhook`
+
+For AI or scripts, do not guess the port. Discover the running service first:
+
+```bash
+nextclaw status --json
+```
+
+Read these fields:
+
+- `endpoints.uiUrl`: base URL for UI and `/webhook`, for example `http://127.0.0.1:55667`.
+- `endpoints.apiUrl`: base URL for API routes, for example `http://127.0.0.1:55667/api`.
+- `remote.runtime.localOrigin`: local origin used by the service-managed remote connector when remote access is enabled.
+
+Then call:
+
+```text
+<endpoints.uiUrl>/webhook
+<endpoints.apiUrl>/health
+<endpoints.apiUrl>/ncp/sessions
+```
+
+## Envelope
+
+The webhook body is an ingress envelope:
+
+```json
+{
+  "type": "agent-run.send",
+  "payload": {}
+}
+```
+
+Contract:
+
+- `type` must be a registered ingress type. Unknown types are rejected instead of being turned into chat messages.
+- Third-party integrations should use `agent-run.send` when they want to trigger an Agent run.
+- Extension ingress types are reserved for the extension SDK/internal extension runtime path unless that integration explicitly uses the SDK contract.
+- `Authorization: Bearer <token>` may be sent. Current agent-run webhook usage does not require it, but the field is already part of the ingress context so stricter verification can be added per ingress type later.
+
+## Trigger a New Agent Session
+
+For normal external tools, use the lightweight `content` shape. NextClaw creates the internal user message id, role, status, timestamp, and session id.
+
+```bash
+curl -sS -X POST http://127.0.0.1:55667/webhook \
+  -H 'content-type: application/json' \
+  --data '{
+    "type": "agent-run.send",
+    "payload": {
+      "metadata": {
+        "title": "Webhook smoke",
+        "label": "Webhook smoke",
+        "session_type": "native",
+        "project_root": "/path/to/project"
+      },
+      "content": [
+        { "type": "text", "text": "Reply exactly: Webhook smoke received" }
+      ]
+    }
+  }'
+```
+
+Successful response:
+
+```json
+{
+  "ok": true,
+  "data": {
+    "sessionId": "ncp-...",
+    "userMessageId": "user-message-...",
+    "assistantMessageId": "...",
+    "runId": "ncp-run-..."
+  }
+}
+```
+
+After success, the new session appears in the UI session list. Use `metadata.title` or `metadata.label` to make webhook-created sessions easy to find.
+
+## Continue an Existing Session
+
+Pass `sessionId` to append a new user turn to an existing NCP session:
+
+```json
+{
+  "type": "agent-run.send",
+  "payload": {
+    "sessionId": "ncp-existing-session",
+    "content": [
+      { "type": "text", "text": "Continue this task from the webhook." }
+    ]
+  }
+}
+```
+
+## Payload Fields
+
+`agent-run.send` accepts exactly one of these input forms:
+
+- `content`: recommended for third-party callers. It is an array of NCP message parts, for example `text`, `file`, `rich-text`, `card`, or `extension` parts.
+- `message`: advanced/internal form. It must be a full NCP message with `id`, `role`, `status`, `timestamp`, and `parts`.
+
+Common fields:
+
+- `sessionId`: optional. Omit it to create a new session.
+- `metadata.title` / `metadata.label`: optional human-readable session title.
+- `metadata.agent_id` or `metadata.agentId`: optional target Agent id.
+- `metadata.session_type` or `metadata.runtime`: optional runtime/session type such as `native`.
+- `metadata.preferred_model` or `metadata.model`: optional model override for the created session.
+- `metadata.project_root`: optional project path associated with the session.
+- `metadata.preferred_thinking` or `metadata.thinking`: optional thinking level preference.
+
+Validation rules:
+
+- Provide `content` or `message`, not both.
+- `content` must be an array.
+- If `sessionId` is present, it must be a non-empty string.
+- The gateway returns `400` when the envelope or payload is invalid.
+- Unsupported ingress types return an error message that includes the unsupported type.
+
+## Quick Verification
+
+```bash
+curl http://127.0.0.1:55667/api/health
+curl http://127.0.0.1:55667/api/ncp/sessions
+```
+
+Use `/api/ncp/sessions` after the webhook call to confirm the created `sessionId`, `metadata.label`, status, and latest activity preview.