deepdebug-local-agent 1.0.22 → 1.1.0

package/.github/workflows/deploy-gcp.yml

@@ -0,0 +1,102 @@
+# Deploy local-agent (Node) to GCP Cloud Run (visionhammer) via WIF.
+# Manual-only: this repo has no develop branch and several active feature
+# branches, so deploys are triggered on demand from the Actions tab. Choose the
+# environment input. Replaces the insptechai Cloud Build path.
+name: Deploy Local Agent to GCP
+
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: 'Target environment'
+        required: true
+        default: 'qa'
+        type: choice
+        options: [qa, prod]
+
+concurrency:
+  group: deploy-local-agent-${{ github.ref }}-${{ inputs.environment }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  id-token: write
+
+env:
+  GCP_PROJECT: visionhammer
+  # EU migration (PLANO-MIGRACAO-EU-PROD.md): PROD moves to europe-west1. The
+  # region comes from repo variables (PROD_REGION / QA_REGION); today's value
+  # stays the default, so nothing changes until the variable is set.
+  GCP_REGION: ${{ inputs.environment == 'prod' && (vars.PROD_REGION || 'us-central1') || (vars.QA_REGION || 'us-central1') }}
+  WIF_PROVIDER: projects/1009366917257/locations/global/workloadIdentityPools/github-pool/providers/github-provider
+  DEPLOYER_SA: github-deployer@visionhammer.iam.gserviceaccount.com
+  AR_IMAGE: us-central1-docker.pkg.dev/visionhammer/visionhammer-docker/local-agent
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.environment == 'prod' && 'production' || 'qa' }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Resolve target (service + tag)
+        id: vars
+        run: |
+          if [ "${{ inputs.environment }}" = "prod" ]; then
+            # PROD only from main: a dispatch from a feature branch must not
+            # reach production (QA may still deploy any branch on purpose).
+            if [ "${GITHUB_REF}" != "refs/heads/main" ]; then
+              echo "::error::PROD deploys only from main (got ${GITHUB_REF})."
+              exit 1
+            fi
+            echo "service=deepdebug-local-agent"    >> "$GITHUB_OUTPUT"
+            echo "tag=prod-${GITHUB_SHA::8}"         >> "$GITHUB_OUTPUT"
+            echo "traffic=canary"                    >> "$GITHUB_OUTPUT"
+          else
+            echo "service=deepdebug-local-agent-qa" >> "$GITHUB_OUTPUT"
+            echo "tag=qa-${GITHUB_SHA::8}"           >> "$GITHUB_OUTPUT"
+            echo "traffic=live"                      >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Authenticate to GCP (WIF)
+        uses: google-github-actions/auth@v2
+        with:
+          workload_identity_provider: ${{ env.WIF_PROVIDER }}
+          service_account: ${{ env.DEPLOYER_SA }}
+
+      - name: Set up gcloud
+        uses: google-github-actions/setup-gcloud@v2
+
+      - name: Configure Docker for Artifact Registry
+        run: gcloud auth configure-docker us-central1-docker.pkg.dev --quiet
+
+      - name: Build & push image (multi-stage Node Dockerfile)
+        run: |
+          IMG="${AR_IMAGE}:${{ steps.vars.outputs.tag }}"
+          docker build --platform=linux/amd64 -t "$IMG" .
+          docker push "$IMG"
+          echo "IMG=$IMG" >> "$GITHUB_ENV"
+
+      - name: Deploy to Cloud Run (image only; preserves env/secrets)
+        run: |
+          # PROD lands at 0% traffic behind a tag (canary); verify the tagged
+          # URL, then promote with `gcloud run services update-traffic`.
+          # QA keeps deploying live. Mirrors vh-api-gateway deploy-gcp.yml.
+          #
+          # --vpc-egress is pinned: gcloud 572 flipped the template to
+          # all-traffic on an image-only update; with no Cloud NAT that cuts
+          # the service's internet egress.
+          EXTRA=""
+          if [ "${{ steps.vars.outputs.traffic }}" = "canary" ]; then
+            EXTRA="--no-traffic --tag ${{ steps.vars.outputs.tag }}"
+          fi
+          gcloud run deploy "${{ steps.vars.outputs.service }}" \
+            --image "$IMG" \
+            --project "$GCP_PROJECT" \
+            --region "$GCP_REGION" \
+            --vpc-egress=private-ranges-only \
+            $EXTRA \
+            --quiet
+
+      - name: Summary
+        run: echo "Deployed **${{ steps.vars.outputs.service }}** with \`$IMG\`" >> "$GITHUB_STEP_SUMMARY"

package/.github/workflows/npm-publish.yml

@@ -7,12 +7,32 @@ on:
       - 'src/**'
       - 'package.json'
       - 'bin/**'
+  # Manual publish (e.g. to ship a security fix that landed while publishing was broken).
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Exact version to publish (e.g. 1.1.0). Empty = automatic patch bump. Must be greater than the highest existing tag and package.json.'
+        required: false
+        type: string
+
+# One publish at a time: two runs would compute the same next version.
+concurrency:
+  group: npm-publish
+  cancel-in-progress: false
+
+# Auth is npm Trusted Publishing (OIDC): no long-lived NPM_TOKEN to expire or leak
+# (security review 2026-10-11, M13). The NPM_TOKEN secret expired and every publish
+# since 2026-04-29 failed with "E404 PUT .../deepdebug-local-agent".
+# One-time setup on npmjs.com (package owner): deepdebug-local-agent -> Settings ->
+# Trusted Publisher -> GitHub Actions: org VISIONHAMMER, repo deepdebug-local-agent,
+# workflow npm-publish.yml.
 
 jobs:
   publish:
     runs-on: ubuntu-latest
     permissions:
       contents: write
+      id-token: write   # OIDC token for npm Trusted Publishing (+ provenance)
 
     steps:
       - name: Checkout
@@ -24,9 +44,13 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '24'
           registry-url: 'https://registry.npmjs.org'
 
+      - name: npm with Trusted Publishing support
+        # OIDC publishing needs npm >= 11.5.1.
+        run: npm install -g npm@^11.5.1 && npm --version
+
       - name: Install dependencies
         run: npm install
 
@@ -40,10 +64,41 @@ jobs:
           git add package-lock.json || true
           git diff --staged --quiet || git commit -m "chore: update package-lock.json [skip ci]"
 
-      - name: Bump patch version
+      - name: Bump version (patch, or the exact dispatch input)
+        env:
+          INPUT_VERSION: ${{ github.event_name == 'workflow_dispatch' && inputs.version || '' }}
         run: |
-          npm version patch -m "ci: auto bump to %s [skip ci]"
-          git push origin main --follow-tags
+          # Bump from max(highest existing tag, package.json) so the new tag can
+          # never collide with an already-pushed tag (package.json had drifted
+          # behind the tags, which made `npm version patch` fail with
+          # "tag vX.Y.Z already exists" on every push to main).
+          git fetch --tags --quiet
+          LATEST_TAG="$(git tag --sort=-v:refname | head -1)"
+          LATEST_TAG="${LATEST_TAG#v}"
+          PKG="$(node -p "require('./package.json').version")"
+          BASE="$(printf '%s\n%s\n' "${LATEST_TAG:-0.0.0}" "$PKG" | sort -V | tail -1)"
+          # Compute the next patch version up front and bump in ONE `npm version`
+          # call. A separate `npm version "$BASE" --no-git-tag-version` rewrites
+          # package.json/package-lock.json whenever the tag is ahead of
+          # package.json, leaving the tree dirty so the following
+          # `npm version patch` aborts with "Git working directory not clean".
+          NEXT="$(node -e 'const [a,b,c]=process.argv[1].split(".").map(Number); console.log(`${a}.${b}.${c+1}`)' "$BASE")"
+          # Release override (workflow_dispatch input `version`, e.g. 1.1.0): used
+          # as-is instead of the patch bump, so a minor/major release is not turned
+          # into 1.1.1 by the automatic bump. Read from env, never interpolated.
+          if [ -n "${INPUT_VERSION}" ]; then
+            if ! printf '%s' "$INPUT_VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+              echo "::error::version input '$INPUT_VERSION' is not X.Y.Z"; exit 1
+            fi
+            if [ "$(printf '%s\n%s\n' "$BASE" "$INPUT_VERSION" | sort -V | tail -1)" != "$INPUT_VERSION" ] || [ "$INPUT_VERSION" = "$BASE" ]; then
+              echo "::error::version input $INPUT_VERSION must be greater than $BASE (highest existing tag/package.json)"; exit 1
+            fi
+            NEXT="$INPUT_VERSION"
+          fi
+          # Commit + tag LOCALLY only. They are pushed after a successful publish, so a
+          # failed publish no longer burns a version (1.0.24..1.0.38 were tagged but
+          # never published while the token was expired).
+          npm version "$NEXT" -m "ci: auto bump to %s [skip ci]"
 
       - name: Check if version exists
         id: version_check
@@ -59,14 +114,20 @@ jobs:
             echo "Version $PACKAGE_VERSION is new"
             echo "exists=false" >> $GITHUB_OUTPUT
           fi
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
       - name: Publish to NPM
         if: steps.version_check.outputs.exists == 'false'
+        # No --provenance: this repository is private and npm rejects provenance
+        # statements for private source repositories (E422 "Unsupported GitHub Actions
+        # source repository visibility"). Trusted Publishing (OIDC) still authenticates
+        # the publish. Re-add --provenance if the repository ever becomes public.
         run: npm publish --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Push version bump and tag
+        run: |
+          # main may have moved while we published: replay the bump commit on top.
+          git pull --rebase origin main
+          git push origin main --follow-tags
 
       - name: Skip publish (version exists)
         if: steps.version_check.outputs.exists == 'true'

package/AGENTS.md

@@ -0,0 +1,21 @@
+# AGENTS.md - deepdebug-local-agent
+
+Instructions for AI coding agents (Codex, Cursor, Copilot, Gemini, Claude Code and others).
+Claude Code also reads `CLAUDE.md`; the same rules apply to every agent.
+
+## Read first
+
+1. `.claude/context.md`: what this repo is in the VisionHammer v2 architecture, its
+   neighbours, where things live, how to run, test, deploy and roll back, and the gotchas.
+2. `.claude/standards/README.md`, then the files it lists: `clean-code.md`, `solid.md`,
+   `simplicity.md`, `layered-architecture.md`, `security-owasp.md`, `testing.md`,
+   `code-review-checklist.md` and `node.md`.
+3. `CLAUDE.md`: repo rules. They win over the generic standards.
+
+## Always
+
+- PRs target `main` (publishes the npm package); Cloud Run deploy is manual.
+- Runs inside customer infrastructure: argument-array process execution, paths confined to the workspace, no LLM calls, no secrets in logs.
+- Never print, log or commit secrets. Provider keys exist only in vh-litellm.
+- Verify on the deployed artefact (curl, revision logs, bundle grep), not only on the diff.
+- Small PRs with one intent each. Open PRs; a human merges them.

package/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+## 1.1.0 (prepared, not yet published)
+
+Security release (security review 2026-10-11, C1 and H4). The agent now fails
+closed by default. Read "Upgrade" before rolling it out to agents whose
+platform side does not sign commands yet.
+
+### Changed defaults
+
+- **Signed commands: `enforce` by default.** `LOCAL_AGENT_SIGNATURE_MODE`
+  defaults to `enforce` (was `warn`) and an unrecognised value also means
+  `enforce`. A request without a valid `X-VH-*` signature is refused.
+- **Loopback bind by default.** Without `LOCAL_AGENT_BIND_HOST`, the agent binds
+  `127.0.0.1` unless a token (`LOCAL_AGENT_TOKEN` / `AGENT_SHARED_SECRET`) or
+  Cloud Run is present (or `LOCAL_AGENT_AUTH` is `compat`/`off`).
+- **Helm: token required, NetworkPolicy deny-ingress.** `config.agentToken`
+  is required (rendered as `LOCAL_AGENT_TOKEN`; `helm template` fails without
+  it). The chart ships a NetworkPolicy that denies all ingress except the peers
+  listed in `networkPolicy.allowFrom` (default: none; the agent talks to the
+  platform over an outbound tunnel). Chart `version`/`appVersion` are now 1.1.0.
+- **H4: no shell for request text.** `/workspace/search` runs grep through
+  `execFile` with an argv list, `/workspace/build-push` validates the workspace
+  id and runs tar through `execFile`, and `/setup/run-auth-command` accepts only
+  allowlisted interactive logins, spawned without a shell.
+- Already in 1.0.35 and unchanged here: exec policy `enforce`, `LOCAL_AGENT_AUTH`
+  loopback/token perimeter (`docs/signed-commands.md`).
+
+### Compatibility with the `X-VH-*` signature
+
+Protocol v1 is unchanged (`VH-AGENT-SIG-V1`, Ed25519 over method, path, body
+hash, tenant, workspace, timestamp, nonce; headers `X-VH-Key-Id`,
+`X-VH-Timestamp`, `X-VH-Nonce`, `X-VH-Tenant-Id`, `X-VH-Workspace-Id`,
+`X-VH-Signature`). The trusted key id is `vh-2026-09`; rotation is
+unchanged. A platform that already signs (vh-api-gateway, visionhammer-agents)
+needs no change. `X-Agent-Token` stays as the second factor.
+
+### Build and release
+
+- Release procedure for an exact version without the automatic patch bump:
+  `docs/releasing.md` (`npm-publish.yml` gains a `version` dispatch input).
+- Optional cosign (keyless) signature, SPDX SBOM and SLSA v1 provenance for the
+  `local-agent-full` image, behind `supply_chain` / `BYOC_SUPPLY_CHAIN`
+  (off by default; `docs/byoc-agent-image.md`).
+- Helm `values.yaml`: removed a dead duplicate `networkPolicy` block (the later
+  key already won; no behaviour change).
+
+### Upgrade
+
+1. Make sure the platform signs requests to this agent (gateway and agents with
+   the signing key) before upgrading an agent in production.
+2. Optional soak: set `LOCAL_AGENT_SIGNATURE_MODE=warn` on the agent, watch
+   `[agent-sig] WARN` and `[exec-policy] WARN`, then remove the override.
+3. Helm: set `config.agentToken` (`--set-file` or an existing secret flow) and,
+   if a caller must reach the pod, list it in `networkPolicy.allowFrom`.
+4. Agents reached directly over the network need a token or
+   `LOCAL_AGENT_BIND_HOST`; otherwise they only answer on `127.0.0.1`.
+5. BYOC: pin the new image as `local-agent-full:1.1.0@sha256:<digest>` in the
+   gateway (`BYOC_AGENT_IMAGE`). Existing agents keep their image until
+   re-provisioned.
+
+### Rollback
+
+- Per agent, without redeploy of the platform: `LOCAL_AGENT_SIGNATURE_MODE=warn`
+  (or `off`), `LOCAL_AGENT_BIND_HOST=0.0.0.0` together with a token,
+  `networkPolicy.enabled=false` in Helm. These are explicit, logged opt-outs.
+- Version rollback: npm `npm i deepdebug-local-agent@1.0.38`; BYOC image: repin
+  the previous `:<semver>@sha256:` (tags are immutable, nothing floats).
+  Note 1.0.38 still defaults signatures to `warn` and binds more widely.

package/CLAUDE.md

@@ -0,0 +1,13 @@
+# CLAUDE.md - deepdebug-local-agent
+
+## Read first
+1. `.claude/context.md`: what this agent is in the v2 architecture (the platform's hands
+   in customer infrastructure), its neighbours, run/test, publish/deploy and gotchas.
+2. `.claude/standards/`: shared VisionHammer standards (clean code, SOLID, OWASP security,
+   layers, simplicity, testing, review checklist, `node.md`).
+3. `README.md`: features, legacy connectors, configuration.
+
+Non-negotiables: no LLM calls and no provider keys here; exec with argument arrays only;
+paths confined to the workspace; never log secrets or raw customer log payloads beyond
+what an incident needs; PRs target `main` (merging publishes the npm package).
+Personal, uncommitted notes go in `CLAUDE.local.md` (gitignored).

package/CLAUDE_CODE_AGENT_INFINITE.md

@@ -13,7 +13,9 @@ AGENT="https://deepdebug-local-agent-qa-575662086506.us-central1.run.app"
 GATEWAY="https://deepdebug-gateway-qa-575662086506.us-central1.run.app"
 GCP_CLIENT="gen-lang-client-0961289539"
 SA_EMAIL="deepdebug-agent@${GCP_CLIENT}.iam.gserviceaccount.com"
-PG="PGPASSWORD='DeepDebugQA@2026' psql -h 35.224.155.29 -U deepdebug -d deepdebug"
+# DB password: never inline it. Read it from Secret Manager (pg-password-qa).
+PG_PASSWORD="$(gcloud secrets versions access latest --secret=pg-password-qa --project=visionhammer)"
+PG="PGPASSWORD=\"$PG_PASSWORD\" psql -h 35.224.155.29 -U deepdebug -d deepdebug"
 WS_ID="b040f1ae-5f3c-4612-9ce1-0b18a5aea303"
 
 log()  { echo "[$(date '+%H:%M:%S')] $1"; }
@@ -517,7 +519,7 @@ while [ "$AGENT_DONE" = "false" ]; do
 
   # ─── CHECK A3: Clone com token real ───
   log "CHECK A3: Clone com token real"
-  GIT_TOKEN=$(PGPASSWORD='DeepDebugQA@2026' psql -h 35.224.155.29 -U deepdebug -d deepdebug -t -c \
+  GIT_TOKEN=$(PGPASSWORD="$PG_PASSWORD" psql -h 35.224.155.29 -U deepdebug -d deepdebug -t -c \
     "SELECT t.access_token FROM oauth_tokens t JOIN tenants tn ON tn.id::text=t.tenant_id WHERE t.provider='GITHUB' LIMIT 1;" \
     | tr -d ' \n')
 
@@ -537,7 +539,7 @@ while [ "$AGENT_DONE" = "false" ]; do
 
   # ─── CHECK A4: /workspace/build-push com SA real ───
   log "CHECK A4: build-push com SA key real"
-  SA_KEY_ENC=$(PGPASSWORD='DeepDebugQA@2026' psql -h 35.224.155.29 -U deepdebug -d deepdebug -t -c \
+  SA_KEY_ENC=$(PGPASSWORD="$PG_PASSWORD" psql -h 35.224.155.29 -U deepdebug -d deepdebug -t -c \
     "SELECT service_account_key FROM oauth_tokens WHERE tenant_id='63922779-7321-4e79-b0f0-63890cd0d98e' AND provider='GCP';" \
     | tr -d ' \n')
   ENC_KEY=$(gcloud secrets versions access latest --secret=encryption-key-qa --project=insptechai 2>/dev/null)

package/Dockerfile

@@ -120,6 +120,10 @@ HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
 ENV NODE_ENV=production
 ENV PORT=5055
 ENV WORKSPACES_MOUNT=/mnt/workspaces
+# env-compat preload: maps legacy env names (DEEPDEBUG_API_URL/TENANT_ID/
+# WORKSPACE_PATH) to the canonical GATEWAY_URL/TENANT_ID/WORKSPACE_ROOT before
+# server.js is evaluated. --require (CJS) runs before the ESM entry module.
+ENV NODE_OPTIONS="--require /app/src/siblings/env-compat.cjs"
 
 EXPOSE 5055
 

package/Dockerfile.full

@@ -33,8 +33,51 @@ RUN apt-get update && \
 ENV JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
 ENV PATH=$PATH:$JAVA_HOME/bin:/usr/share/maven/bin
 
+# Swift 5.10 toolchain — enables `swift build` for SwiftPM projects and
+# `swiftc -typecheck` / `swiftc -parse` for iOS/Xcode projects whose imports
+# Linux can resolve. Apple-framework imports (UIKit/SwiftUI/Combine/etc.)
+# still need macOS — handled gracefully in src/exec-utils.js by falling
+# back to `swiftc -parse` (syntax-only validation).
+# Image-size cost: ~1.5 GB decompressed. Accepted for the BYOC full-tools
+# agent image; not pulled by the lean Cloud Run QA path (uses Dockerfile).
+# Note on platform mismatch: base is node:20-slim (Debian 12/bookworm), but
+# swift.org does not publish a debian12 tarball for 5.10. Ubuntu 22.04 build
+# runs cleanly on Debian 12 (newer glibc is backward-compatible with the
+# ubuntu2204 binary), so we install the ubuntu22.04 tarball + Debian 12
+# runtime deps. swift --version smoke-test catches any glibc mismatch at
+# build time.
+ARG SWIFT_VERSION=5.10
+ARG SWIFT_PLATFORM=ubuntu22.04
+ARG SWIFT_PLATFORM_DIR=ubuntu2204
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+        binutils \
+        libc6-dev \
+        libcurl4-openssl-dev \
+        libedit2 \
+        libgcc-12-dev \
+        libncurses6 \
+        libpython3.11 \
+        libsqlite3-0 \
+        libstdc++-12-dev \
+        libxml2-dev \
+        libz3-dev \
+        pkg-config \
+        tzdata \
+        uuid-dev \
+        zlib1g-dev \
+        && rm -rf /var/lib/apt/lists/* \
+    && cd /tmp \
+    && curl -fsSL "https://download.swift.org/swift-${SWIFT_VERSION}-release/${SWIFT_PLATFORM_DIR}/swift-${SWIFT_VERSION}-RELEASE/swift-${SWIFT_VERSION}-RELEASE-${SWIFT_PLATFORM}.tar.gz" -o swift.tar.gz \
+    && tar xzf swift.tar.gz \
+    && mv "swift-${SWIFT_VERSION}-RELEASE-${SWIFT_PLATFORM}" /opt/swift \
+    && rm swift.tar.gz \
+    && ln -s /opt/swift/usr/bin/swift /usr/local/bin/swift \
+    && ln -s /opt/swift/usr/bin/swiftc /usr/local/bin/swiftc \
+    && swift --version
+
 # Verify all tools are installed
-RUN java -version && mvn -version && node -v && git --version
+RUN java -version && mvn -version && node -v && git --version && swift --version
 
 # Git safe directory for NFS mounted workspaces
 RUN git config --global --add safe.directory '*'
@@ -55,9 +98,18 @@ RUN mkdir -p /home/deepdebug/.m2 && chown -R deepdebug:deepdebug /home/deepdebug
 # Workspace mount point
 RUN mkdir -p /mnt/workspaces && chown -R deepdebug:deepdebug /mnt/workspaces
 
-EXPOSE 8080
+# Port aligned to 5055 to match Dockerfile, docker-compose, Helm and the
+# server.js default (PORT || LOCAL_AGENT_PORT || 5055). 8080 here conflicted.
+EXPOSE 5055
 
 ENV NODE_ENV=production
-ENV PORT=8080
+ENV PORT=5055
+# env-compat preload (see Dockerfile): legacy->canonical env mapping before eval.
+ENV NODE_OPTIONS="--require /app/src/siblings/env-compat.cjs"
+
+# SECURITY (2026-10-11): the slim Dockerfile already drops to the unprivileged
+# user; this image ran everything (model-authored commands included) as root.
+RUN su deepdebug -c "git config --global --add safe.directory '*'"
+USER deepdebug
 
 CMD ["node", "src/server.js"]

package/README.md

@@ -0,0 +1,81 @@
+# DeepDebug Local Agent
+
+AI-powered on-prem ingestion arm of the VisionHammer / DeepDebug pipeline. The
+local agent watches application logs, surfaces incidents, and forwards them to
+the gateway for downstream analysis.
+
+- **Runtime:** Node.js 18+ (pure ESM, `"type": "module"`)
+- **Test runner:** `node:test` (Node built-in)
+- **Distribution:** `npm install` for development; `pkg`-bundled binaries for
+  production install (`npm run build:all`)
+- **Package:** `deepdebug-local-agent@1.0.21`
+
+## Quick start
+
+```bash
+npm install
+npm test           # runs node --test (52 tests across adapters + registry)
+npm start          # boots the agent (default port 5055; MCP bridge on 5056)
+```
+
+Configuration lives in `~/.deepdebug/config.json` and via env vars (`PORT`,
+`MCP_PORT`, `GATEWAY_URL`, `DEEPDEBUG_API_KEY`, `TENANT_ID`,
+`DISABLE_WS_TUNNEL`, `LEGACY_STACKS`).
+
+Companion docs:
+
+- [QUICKSTART.md](./docs/QUICKSTART.md) — end-user install + first-run
+- [ENTERPRISE_DEPLOYMENT_GUIDE.md](./docs/ENTERPRISE_DEPLOYMENT_GUIDE.md)
+- [SECURITY_WHITEPAPER.md](./docs/SECURITY_WHITEPAPER.md)
+- [docs/legacy-connectors.md](./docs/legacy-connectors.md) — **Phase 2** legacy
+  stack ingestion reference
+
+## Features
+
+- Real-time application log ingestion via `processManager.on('log', ...)`
+- AI-driven patch generation (`AIVibeCodingEngine`) wired to the gateway
+- Workspace-scoped operations via the workspace manager
+- Backup / restore with disk-indexed history
+- WebSocket reverse tunnel to the gateway (`startWebSocketTunnel`)
+- MCP HTTP bridge (`startMCPHttpServer` on port 5056)
+- **Legacy connectors** — five EventEmitter adapters for legacy on-prem stacks
+  (see below)
+
+## Legacy connectors
+
+DeepDebug Local Agent ships five EventEmitter adapters for legacy on-prem
+stacks, behind a single `LEGACY_STACKS` env var:
+
+- **SAP** (`src/adapters/sap/`) — watches SAP NetWeaver `dev_w*` work-process
+  traces + `SLOG*` system logs
+- **IBM MQ** (`src/adapters/ibmmq/`) — watches `AMQERR0[1-3].LOG` files
+- **AS/400** (`src/adapters/as400/`) — polls DSPLOG via SSH with auto-reconnect
+- **Oracle Forms** (`src/adapters/oracle-forms/`) — watches `*.trc` trace files
+  (Latin-1 tolerant)
+- **COBOL/Mainframe** (`src/adapters/cobol/`) — watches JES2 spool exports
+  (CRLF + 80-col tolerant)
+
+Each adapter emits `error` events with a frozen 6-key shape:
+`{adapter, errorCode, file, message, source, timestamp}`.
+
+To enable: set `LEGACY_STACKS=sap,cobol` (comma-separated subset of
+`sap,ibmmq,as400,oracle-forms,cobol`) in the agent's environment. When unset,
+the adapters are not loaded and the local-agent boot path is byte-for-byte
+unchanged.
+
+Full configuration + troubleshooting reference:
+[docs/legacy-connectors.md](./docs/legacy-connectors.md).
+
+## Development
+
+```bash
+npm test                 # full suite (52 tests)
+npm run sync-fixtures    # refresh test/fixtures/<stack>/ from example repos
+                         # (requires ~/.config/visionhammer/github-pat)
+npm run lint             # eslint src/
+npm run dev              # NODE_ENV=development node src/server.js
+```
+
+## License
+
+Proprietary — InspTech AI.

package/bin/install.js

@@ -17,7 +17,7 @@ import fs from 'fs';
 import path from 'path';
 import os from 'os';
 import crypto from 'crypto';
-import { spawn, execSync } from 'child_process';
+import { spawn, execSync, execFileSync } from 'child_process';
 import readline from 'readline';
 
 // ============================================
@@ -26,7 +26,14 @@ import readline from 'readline';
 const CONFIG_DIR = path.join(os.homedir(), '.deepdebug');
 const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
 const MACHINE_ID_FILE = path.join(CONFIG_DIR, 'machine-id');
-const API_BASE_URL = process.env.DEEPDEBUG_API_URL || 'https://deepdebug-gateway-lszyf7c4ia-uc.a.run.app';
+// Single-sourced default, consistent with docker-compose / Helm / env.example /
+// canonical prod host. Verified against DNS + Cloud Run domain mapping:
+// api.visionhammer.io -> ghs.googlehosted.com (Cloud Run mapping for the prod
+// deepdebug-gateway service). api.deepdebug.ai has NO DNS record and did not
+// answer during the audit, so it must NOT be the default. The previous default
+// was also a stale, now-dead QA run.app hash (deepdebug-gateway-lszyf7c4ia).
+// Override per environment with DEEPDEBUG_API_URL.
+const API_BASE_URL = process.env.DEEPDEBUG_API_URL || 'https://api.visionhammer.io';
 const DOCKER_IMAGE = 'williambella/deepdebug-local-agent:latest';
 
 // ============================================
@@ -421,7 +428,7 @@ function startDockerAgent(config) {
         } catch {}
 
         logInfo('Pulling latest DeepDebug Local Agent image...');
-        execSync(`docker pull ${DOCKER_IMAGE}`, { stdio: 'inherit' });
+        execFileSync('docker', ['pull', DOCKER_IMAGE], { stdio: 'inherit' });
 
         // Prepare paths for Docker
         let configMount = CONFIG_DIR;
@@ -436,7 +443,9 @@ function startDockerAgent(config) {
         const dockerArgs = [
             'run', '-d',
             '--name', 'deepdebug-agent',
-            '-p', '5055:5055',
+            // SECURITY: publish on loopback only. '5055:5055' exposed the agent
+            // (shell exec + workspace write API) on every host interface.
+            '-p', '127.0.0.1:5055:5055',
             '-v', `${configMount}:/home/deepdebug/.deepdebug:ro`,
             '-v', `${projectsMount}:/workspace:rw`,
             '-e', `GATEWAY_URL=${config.gatewayUrl}`,
@@ -448,7 +457,9 @@ function startDockerAgent(config) {
         ];
 
         logInfo('Starting Docker container with workspace mounted...');
-        execSync(`docker ${dockerArgs.join(' ')}`, { stdio: 'inherit' });
+        // execFileSync (no shell): paths/config values are passed verbatim, so a
+        // projects path with spaces or shell metacharacters cannot break out.
+        execFileSync('docker', dockerArgs, { stdio: 'inherit' });
         logSuccess('DeepDebug Local Agent started successfully!');
         return true;
     } catch (error) {

package/cloudbuild-full.yaml

@@ -0,0 +1,57 @@
+# Manual fallback for the BYOC "full" agent image (the primary path is the
+# GitHub Actions workflow .github/workflows/build-byoc-image.yml).
+# Replaces cloudbuild-full-v3.yaml, which pushed a floating :v3 tag to the
+# deactivated insptechai project.
+#
+# Usage (from a clean checkout of main; both substitutions are required):
+#   gcloud builds submit --project visionhammer --config cloudbuild-full.yaml \
+#     --substitutions=_VERSION=1.0.31,_GIT_SHA=$(git rev-parse HEAD) .
+#
+# Pushes :<_VERSION> and :<_GIT_SHA> — never a floating tag. Pin the gateway to
+# the resulting digest (deepdebug.byoc.agent-image in vh-api-gateway).
+substitutions:
+  _IMAGE: 'us-central1-docker.pkg.dev/visionhammer/visionhammer-docker-public/local-agent-full'
+  _VERSION: ''
+  _GIT_SHA: ''
+
+steps:
+  - id: guard
+    name: 'gcr.io/cloud-builders/gcloud'
+    entrypoint: 'bash'
+    args:
+      - '-c'
+      - |
+        set -euo pipefail
+        [ -n "${_VERSION}" ] && [ -n "${_GIT_SHA}" ] || { echo "_VERSION and _GIT_SHA are required"; exit 1; }
+        if gcloud artifacts docker images describe "${_IMAGE}:${_VERSION}" >/dev/null 2>&1; then
+          echo "${_IMAGE}:${_VERSION} already exists; bump the version instead of overwriting"; exit 1
+        fi
+
+  - id: build
+    name: 'gcr.io/cloud-builders/docker'
+    args:
+      - 'build'
+      - '--platform=linux/amd64'
+      - '-f'
+      - 'Dockerfile.full'
+      - '--label'
+      - 'org.opencontainers.image.revision=${_GIT_SHA}'
+      - '--label'
+      - 'org.opencontainers.image.version=${_VERSION}'
+      - '-t'
+      - '${_IMAGE}:${_VERSION}'
+      - '-t'
+      - '${_IMAGE}:${_GIT_SHA}'
+      - '.'
+    timeout: '3000s'
+
+images:
+  - '${_IMAGE}:${_VERSION}'
+  - '${_IMAGE}:${_GIT_SHA}'
+
+options:
+  logging: CLOUD_LOGGING_ONLY
+  machineType: 'E2_HIGHCPU_32'
+  diskSizeGb: 50
+
+timeout: '3600s'

package/docker-compose.yml

@@ -63,9 +63,11 @@ services:
     environment:
       - NODE_ENV=production
       - PORT=5055
-      - DEEPDEBUG_API_URL=${DEEPDEBUG_API_URL:-https://api.deepdebug.ai}
-      - DEEPDEBUG_TENANT_ID=${DEEPDEBUG_TENANT_ID}
-      - DEEPDEBUG_WORKSPACE_PATH=/workspace
+      # Names aligned to what src/server.js actually reads (server.js is frozen):
+      # GATEWAY_URL (server.js:73), TENANT_ID (:7505), WORKSPACE_ROOT (:637).
+      - GATEWAY_URL=${GATEWAY_URL:-https://api.deepdebug.ai}
+      - TENANT_ID=${TENANT_ID}
+      - WORKSPACE_ROOT=/workspace
       - LOG_LEVEL=${LOG_LEVEL:-info}
 
     # ─────────────────────────────────────────