unaltraweb 0.5.1 → 0.7.0

data/scripts/unaltraweb-mcp-bootstrap.sh

@@ -3,18 +3,28 @@ set -eu
 
 usage() {
   cat <<'USAGE'
-Usage: unaltraweb-mcp-bootstrap [--project PATH] [--image IMAGE] [--prepare|--check|--smoke]
+Usage: unaltraweb-mcp-bootstrap [--project PATH] [--host-project PATH] [--image IMAGE]
+       [--expected-image-id ID] [--managed] [--offline] [--session-id ID] [--worker-images JSON]
+       [--prepare|--check|--smoke]
 
 Start one Dockerized unaltraweb MCP stdio server for the selected workspace.
 If --project is omitted, MCP_CONSUMER_WORKSPACE is used, then the current directory.
 --prepare inspects or pulls the selected image without mounting a consumer.
---check and --smoke require that image locally; neither builds nor pulls.
+Launch, --check and --smoke require that exact image locally; none builds or pulls.
+Managed mode requires an immutable reference or an expected full image ID.
 USAGE
 }
 
-image="${UNALTRAWEB_MCP_IMAGE:-ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:36d17edbade77edb40a687f6a744203c6329acb33fbc2eb255e88d9ff1a42c98}"
+image="${UNALTRAWEB_MCP_IMAGE:-ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:736c4ddd0a543454e3edaeac2e9cfd97a1279ce472923ac54e326c1281b2ba05}"
 project="${MCP_CONSUMER_WORKSPACE:-${UNALTRAWEB_PROJECT:-}}"
 operation=serve
+expected_image="${UNALTRAWEB_EXPECTED_IMAGE_ID:-}"
+managed="${UNALTRAWEB_MANAGED_RUNTIME:-0}"
+session_id=""
+host_project=""
+network=bridge
+worker_images="${UNALTRAWEB_WORKER_IMAGES:-}"
+[ -n "$worker_images" ] || worker_images='{}'
 
 while [ "$#" -gt 0 ]; do
   case "$1" in
@@ -28,6 +38,18 @@ while [ "$#" -gt 0 ]; do
       image="$2"
       shift 2
       ;;
+    --host-project|--expected-image-id|--session-id|--worker-images)
+      [ "$#" -ge 2 ] || { printf 'Missing value for %s\n' "$1" >&2; exit 2; }
+      case "$1" in
+        --host-project) host_project=$2 ;;
+        --expected-image-id) expected_image=$2 ;;
+        --session-id) session_id=$2 ;;
+        --worker-images) worker_images=$2 ;;
+      esac
+      shift 2
+      ;;
+    --managed) managed=1; shift ;;
+    --offline) network=none; shift ;;
     --prepare|--check|--smoke)
       [ "$operation" = serve ] || { printf '%s\n' 'Select only one operation.' >&2; exit 2; }
       operation="${1#--}"
@@ -45,10 +67,33 @@ while [ "$#" -gt 0 ]; do
   esac
 done
 
+valid_image_id() {
+  case "$1" in sha256:*) hex=${1#sha256:} ;; *) return 1 ;; esac
+  [ "${#hex}" -eq 64 ] || return 1
+  case "$hex" in *[!0-9a-f]*) return 1 ;; esac
+}
+case "$image" in ''|*[!A-Za-z0-9._/:@-]*) printf '%s\n' 'Invalid image reference' >&2; exit 2 ;; esac
+case "$image" in *://*) printf '%s\n' 'Docker references are not URLs' >&2; exit 2 ;; esac
+case "$image" in
+  *@*)
+    valid_image_id "${image##*@}" || { printf '%s\n' 'Invalid digest reference' >&2; exit 2; }
+    case "${image%@*}" in *@*) printf '%s\n' 'Invalid digest reference' >&2; exit 2 ;; esac
+    ;;
+esac
+if [ -n "$expected_image" ]; then
+  valid_image_id "$expected_image" || { printf '%s\n' 'Expected image ID must be a full lowercase sha256' >&2; exit 2; }
+  managed=1
+fi
+case "$image" in
+  sha256:*) valid_image_id "$image" || exit 2; managed=1 ;;
+  *@sha256:*) valid_image_id "sha256:${image##*@sha256:}" || exit 2; managed=1 ;;
+  *) if [ "$managed" = 1 ] && [ -z "$expected_image" ]; then printf '%s\n' 'Managed mutable references require --expected-image-id' >&2; exit 2; fi ;;
+esac
+
 resolve_image() {
   if ! resolved_image="$(docker image inspect --format '{{.Id}}' "$image" 2>/dev/null)"; then
     case "$operation" in
-      check|smoke)
+      serve|check|smoke)
         printf 'Image is not prepared: %s. Run --prepare first.\n' "$image" >&2
         exit 1
         ;;
@@ -56,14 +101,19 @@ resolve_image() {
     docker pull "$image" >&2
     resolved_image="$(docker image inspect --format '{{.Id}}' "$image")"
   fi
+  valid_image_id "$resolved_image" || { printf '%s\n' 'Docker returned an invalid image identity' >&2; exit 2; }
+  case "$image" in sha256:*) [ "$image" = "$resolved_image" ] || { printf '%s\n' 'Selected image ID mismatch' >&2; exit 1; } ;; esac
+  if [ -n "$expected_image" ] && [ "$expected_image" != "$resolved_image" ]; then
+    printf '%s\n' 'Prepared image does not match the expected image ID; no fallback was attempted' >&2; exit 1
+  fi
 }
 
 if [ "$operation" != serve ]; then
   resolve_image
   case "$operation" in
     prepare) printf '%s\n' "$resolved_image"; exit 0 ;;
-    check) exec docker run --rm --network none --user "$(id -u):$(id -g)" -e HOME=/tmp --entrypoint unaltraweb-mcp "$resolved_image" version ;;
-    smoke) exec docker run --rm --network none --user "$(id -u):$(id -g)" -e HOME=/tmp --entrypoint python3 "$resolved_image" /opt/unaltraweb/test/mcp_smoke.py ;;
+    check) exec docker run --rm --pull never --network none --user "$(id -u):$(id -g)" -e HOME=/tmp --entrypoint unaltraweb-mcp "$resolved_image" version ;;
+    smoke) exec docker run --rm --pull never --network none --user "$(id -u):$(id -g)" -e HOME=/tmp --entrypoint python3 "$resolved_image" /opt/unaltraweb/test/mcp_smoke.py ;;
   esac
 fi
 
@@ -85,10 +135,28 @@ if [ ! -d "$project" ]; then
 fi
 
 project="$(CDPATH= cd -- "$project" && pwd -P)"
+launcher_project="$project"
+if [ -z "$host_project" ]; then
+  host_project="${UNALTRAWEB_DOCKER_ROOT:-}"
+  if [ -n "$host_project" ]; then
+    inherited_workspace="${MCP_CONSUMER_WORKSPACE:-}"
+    if [ -z "$inherited_workspace" ] || [ ! -d "$inherited_workspace" ] || [ "$(CDPATH= cd -- "$inherited_workspace" && pwd -P)" != "$launcher_project" ]; then
+      printf '%s\n' 'Inherited daemon mapping belongs to another or unknown workspace; pass --host-project explicitly' >&2; exit 2
+    fi
+  fi
+fi
+if [ -z "$host_project" ] && [ -f /.dockerenv ]; then
+  printf '%s\n' 'A containerized launcher needs --host-project with the explicit daemon-host mapping' >&2; exit 2
+fi
+host_project="${host_project:-$project}"
+case "$host_project" in /*) ;; *) printf '%s\n' 'Host project must be absolute' >&2; exit 2 ;; esac
+case "$host_project" in *"$newline"*|*"$carriage_return"*) exit 2 ;; esac
+[ "$host_project" != / ] && [ "$(realpath -ms -- "$host_project")" = "$host_project" ] || { printf '%s\n' 'Host project must be normalized' >&2; exit 2; }
+project="$host_project"
 owner="${UNALTRAWEB_PROJECT_USER:-$(id -u):$(id -g)}"
 docker_socket="${UNALTRAWEB_DOCKER_SOCKET:-/var/run/docker.sock}"
 script_dir="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd -P)"
-project_id="$(/bin/sh "$script_dir/unaltraweb-mcp-project-id.sh" "$project")"
+project_id="$(printf '%s' "$project" | sha256sum | cut -c 1-16)"
 workspace_mount="$(/bin/sh "$script_dir/unaltraweb-docker-mount.sh" "$project" /workspace)"
 mirror_mount="$(/bin/sh "$script_dir/unaltraweb-docker-mount.sh" "$project" "$project")"
 
@@ -103,7 +171,7 @@ if [ -S "$docker_socket" ]; then
     exit 1
   fi
   case "$docker_socket" in
-    "$project"|"$project"/*)
+    "$project"|"$project"/*|"$launcher_project"|"$launcher_project"/*)
       printf '%s\n' 'UNALTRAWEB_DOCKER_SOCKET must be outside the consumer project so the persistent preview cannot inherit it.' >&2
       exit 1
       ;;
@@ -111,6 +179,9 @@ if [ -S "$docker_socket" ]; then
 fi
 
 resolve_image
+if [ -z "$session_id" ]; then session_id=$(od -An -N16 -tx1 /dev/urandom | tr -d ' \n'); fi
+[ "${#session_id}" -eq 32 ] || { printf '%s\n' 'Session ID must contain 32 lowercase hex characters' >&2; exit 2; }
+case "$session_id" in *[!0-9a-f]*) exit 2 ;; esac
 image_reference="$image"
 case "$image_reference" in
   ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:*) ;;
@@ -123,10 +194,13 @@ case "$image_reference" in
     ;;
 esac
 
-set -- docker run --rm -i \
+set -- docker run --rm --pull never --init -i \
+  --network "$network" \
+  --name "unaltraweb-stdio-$session_id" --cpus 2 --memory 4g --pids-limit 512 \
   --label io.context.mcp-factory=unaltraweb \
   --label io.context.mcp-role=stdio \
   --label "io.context.mcp-project=$project_id" \
+  --label "io.context.mcp-session=$session_id" \
   --user "$owner" \
   -e HOME=/tmp \
   -e COMPUTE_CORE=/opt/unaltraweb \
@@ -136,6 +210,13 @@ set -- docker run --rm -i \
   -e UNALTRAWEB_FACTORY_DIR=/opt/unaltraweb \
   -e "UNALTRAWEB_MCP_IMAGE=$resolved_image" \
   -e "UNALTRAWEB_MCP_IMAGE_REFERENCE=$image_reference" \
+  -e "UNALTRAWEB_MCP_REQUESTED_IMAGE=$image" \
+  -e "UNALTRAWEB_EXPECTED_IMAGE_ID=$resolved_image" \
+  -e "UNALTRAWEB_RUNTIME_SESSION=$session_id" \
+  -e "UNALTRAWEB_MANAGED_RUNTIME=$managed" \
+  -e "UNALTRAWEB_RUNTIME_NETWORK=$network" \
+  -e "UNALTRAWEB_LAUNCHER_PROJECT=$launcher_project" \
+  -e "UNALTRAWEB_WORKER_IMAGES=$worker_images" \
   -e "UNALTRAWEB_PROJECT_USER=$owner" \
   --mount "$workspace_mount" \
   --mount "$mirror_mount" \

data/scripts/unaltraweb-mcp-cleanup.sh

@@ -58,16 +58,48 @@ case "$project_id" in
     ;;
 esac
 
-containers=$(docker ps -aq \
+# Explicit workspace-wide shutdown. Managed per-client detach uses live drain,
+# stdio EOF and the separate session-status/reap-session native adapter instead.
+containers=$(docker ps -aq --no-trunc \
   --filter "label=io.context.mcp-factory=unaltraweb" \
   --filter "label=io.context.mcp-project=$project_id")
-if [ -n "$containers" ]; then
-  docker rm -f $containers >/dev/null
-fi
-
-networks=$(docker network ls -q \
+networks=$(docker network ls -q --no-trunc \
   --filter "label=io.context.mcp-factory=unaltraweb" \
   --filter "label=io.context.mcp-project=$project_id")
-if [ -n "$networks" ]; then
-  docker network rm $networks >/dev/null
-fi
+
+valid_id() {
+  [ "${#1}" -eq 64 ] || return 1
+  case "$1" in *[!0-9a-f]*) return 1 ;; esac
+}
+count=0
+for cid in $containers; do
+  count=$((count + 1))
+  [ "$count" -le 64 ] && valid_id "$cid" || { printf '%s\n' 'Container inventory is invalid or exceeds bounds' >&2; exit 2; }
+  labels=$(docker container inspect --format '{{index .Config.Labels "io.context.mcp-factory"}}|{{index .Config.Labels "io.context.mcp-role"}}|{{index .Config.Labels "io.context.mcp-project"}}' "$cid")
+  case "$labels" in
+    "unaltraweb|stdio|$project_id"|"unaltraweb|preview|$project_id"|"unaltraweb|computation|$project_id"|"unaltraweb|manual-pdf|$project_id"|"unaltraweb|web-capture|$project_id"|"unaltraweb|web-capture-site|$project_id") ;;
+    *) printf '%s\n' 'Refusing unknown container ownership' >&2; exit 2 ;;
+  esac
+done
+for nid in $networks; do
+  count=$((count + 1))
+  [ "$count" -le 64 ] && valid_id "$nid" || { printf '%s\n' 'Network inventory is invalid or exceeds bounds' >&2; exit 2; }
+  labels=$(docker network inspect --format '{{index .Labels "io.context.mcp-factory"}}|{{index .Labels "io.context.mcp-role"}}|{{index .Labels "io.context.mcp-project"}}' "$nid")
+  [ "$labels" = "unaltraweb|web-capture|$project_id" ] || { printf '%s\n' 'Refusing unknown network ownership' >&2; exit 2; }
+done
+if [ -n "$containers" ]; then docker rm -f $containers >/dev/null; fi
+if [ -n "$networks" ]; then docker network rm $networks >/dev/null; fi
+for cid in $containers; do
+  if observed=$(docker container inspect --format '{{.Id}}' "$cid" 2>&1); then
+    printf '%s\n' 'Container termination is not confirmed' >&2; exit 1
+  else
+    case "$observed" in *"No such container"*|*"no such container"*|*"No such object"*) ;; *) printf '%s\n' 'Container absence is unknown' >&2; exit 1 ;; esac
+  fi
+done
+for nid in $networks; do
+  if observed=$(docker network inspect --format '{{.Id}}' "$nid" 2>&1); then
+    printf '%s\n' 'Network removal is not confirmed' >&2; exit 1
+  else
+    case "$observed" in *"No such network"*|*"no such network"*|*"No such object"*) ;; *) printf '%s\n' 'Network absence is unknown' >&2; exit 1 ;; esac
+  fi
+done

data/scripts/web_captures/render.py

@@ -588,6 +588,8 @@ def internal_network(network: str) -> bool:
 
 def build_image(image: str) -> None:
     available = inspect_image(image)["available"] == "true"
+    if not available and os.environ.get("UNALTRAWEB_MANAGED_RUNTIME") == "1":
+        raise WebCaptureError("Selected capture image is not prepared; managed execution never pulls")
     if available:
         return
     completed = subprocess.run(["docker", "pull", image], check=False)
@@ -722,6 +724,9 @@ def run_worker(project: Path, image: str, config_path: Path) -> None:
         "project": os.environ.get("UNALTRAWEB_WORKER_PROJECT", "").strip(),
         "token": os.environ.get("UNALTRAWEB_WORKER_TOKEN", "").strip(),
     }
+    session = os.environ.get("UNALTRAWEB_RUNTIME_SESSION", "")
+    if session and not re.fullmatch(r"[0-9a-f]{32}", session):
+        raise WebCaptureError("Invalid runtime session identity")
     worker_args: list[str] = []
     cidfile: Path | None = None
     if any(worker_values.values()):
@@ -739,7 +744,9 @@ def run_worker(project: Path, image: str, config_path: Path) -> None:
             "--label", f"io.context.mcp-worker-token={worker_values['token']}",
         ]
     command = [
-        "docker", "run", "--rm", *worker_args, "--user", f"{os.getuid()}:{os.getgid()}", "--network", network, "--ipc=host",
+        "docker", "run", "--rm", "--pull", "never", *worker_args,
+        *(["--label", f"io.context.mcp-session={session}"] if session else []),
+        "--user", f"{os.getuid()}:{os.getgid()}", "--network", network, "--ipc=host",
         "--read-only", "--cap-drop", "ALL", "--security-opt", "no-new-privileges", "--pids-limit", "256", "--cpus", "2", "--memory", "2g",
         "--tmpfs", "/tmp:rw,noexec,nosuid,size=512m", "-e", "HOME=/tmp",
         "--mount", docker_bind_mount(project, "/project"), "-w", "/project", image,

data/src/unaltraweb_mcp/__init__.py

@@ -0,0 +1,4 @@
+from .distribution import distribution_version
+
+
+__version__ = distribution_version()

data/src/unaltraweb_mcp/artifact-handoff-v1.schema.json

@@ -0,0 +1,102 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "MCP artifact handoff v1 (review candidate)",
+  "oneOf": [
+    {"$ref": "#/$defs/bundle"},
+    {"$ref": "#/$defs/integration"}
+  ],
+  "$defs": {
+    "id": {"type": "string", "pattern": "^[a-z][a-z0-9._-]{0,79}$"},
+    "hash": {"type": "string", "pattern": "^[0-9a-f]{64}$"},
+    "revision": {"type": "string", "pattern": "^(git:([0-9a-f]{40}|[0-9a-f]{64})|sha256:[0-9a-f]{64})$"},
+    "path": {"type": "string", "minLength": 1, "maxLength": 1024},
+    "runtime": {
+      "type": "object", "additionalProperties": false,
+      "required": ["name", "revision"],
+      "properties": {
+        "name": {"$ref": "#/$defs/id"},
+        "revision": {"$ref": "#/$defs/revision"}
+      }
+    },
+    "actor": {
+      "type": "object", "additionalProperties": false,
+      "required": ["name", "version", "revision", "runtimes"],
+      "properties": {
+        "name": {"$ref": "#/$defs/id"},
+        "version": {"type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[A-Za-z0-9][A-Za-z0-9._+-]*$"},
+        "revision": {"$ref": "#/$defs/revision"},
+        "runtimes": {"type": "array", "maxItems": 32, "items": {"$ref": "#/$defs/runtime"}}
+      }
+    },
+    "dependency": {
+      "type": "object", "additionalProperties": false,
+      "required": ["id", "sha256"],
+      "properties": {
+        "id": {"$ref": "#/$defs/id"},
+        "sha256": {"$ref": "#/$defs/hash"}
+      }
+    },
+    "upstream": {
+      "type": "object", "additionalProperties": false,
+      "required": ["dependency", "file"],
+      "properties": {
+        "dependency": {"$ref": "#/$defs/id"},
+        "file": {"$ref": "#/$defs/id"}
+      }
+    },
+    "file": {
+      "type": "object", "additionalProperties": false,
+      "required": ["id", "path", "kind", "role", "ownership", "sha256", "bytes"],
+      "properties": {
+        "id": {"$ref": "#/$defs/id"},
+        "path": {"$ref": "#/$defs/path"},
+        "kind": {"enum": ["input", "output", "evidence"]},
+        "role": {"$ref": "#/$defs/id"},
+        "ownership": {"enum": ["author", "producer"]},
+        "sha256": {"$ref": "#/$defs/hash"},
+        "bytes": {"type": "integer", "minimum": 0, "maximum": 536870912},
+        "variant_of": {"$ref": "#/$defs/id"},
+        "from": {"$ref": "#/$defs/upstream"}
+      }
+    },
+    "bundle": {
+      "type": "object", "additionalProperties": false,
+      "required": ["schema_version", "kind", "producer", "request", "files", "dependencies"],
+      "properties": {
+        "schema_version": {"type": "integer", "const": 1},
+        "kind": {"const": "mcp-artifact-bundle"},
+        "producer": {"$ref": "#/$defs/actor"},
+        "request": {"$ref": "#/$defs/id"},
+        "files": {"type": "array", "minItems": 2, "maxItems": 10000, "items": {"$ref": "#/$defs/file"}},
+        "dependencies": {"type": "array", "maxItems": 63, "items": {"$ref": "#/$defs/dependency"}}
+      }
+    },
+    "retained_bundle": {
+      "type": "object", "additionalProperties": false,
+      "required": ["path", "sha256"],
+      "properties": {
+        "path": {"$ref": "#/$defs/path"},
+        "sha256": {"$ref": "#/$defs/hash"}
+      }
+    },
+    "mapping": {
+      "type": "object", "additionalProperties": false,
+      "required": ["source", "destination"],
+      "properties": {
+        "source": {"$ref": "#/$defs/path"},
+        "destination": {"$ref": "#/$defs/path"}
+      }
+    },
+    "integration": {
+      "type": "object", "additionalProperties": false,
+      "required": ["schema_version", "kind", "integrator", "bundle", "mappings"],
+      "properties": {
+        "schema_version": {"type": "integer", "const": 1},
+        "kind": {"const": "mcp-artifact-integration"},
+        "integrator": {"$ref": "#/$defs/actor"},
+        "bundle": {"$ref": "#/$defs/retained_bundle"},
+        "mappings": {"type": "array", "minItems": 1, "maxItems": 10000, "items": {"$ref": "#/$defs/mapping"}}
+      }
+    }
+  }
+}