api/run_turn.sh

#!/usr/bin/env bash
set -euo pipefail

ROOT="$(cd "$(dirname "$0")/.." && pwd)"
USER_INPUT="${1:-}"
MANIFEST_PATH="${2:-}"
INFERENCE_CONFIG_PATH="$ROOT/inference.yaml"
INFERENCE_SCHEMA_PATH="$ROOT/schemas/inference_output_v0.json"

if [ -z "$USER_INPUT" ]; then
  echo "usage: ./api/run_turn.sh <user_input> [manifest.json]" >&2
  exit 1
fi

TURN_ID="$(date -u +"%Y%m%dT%H%M%SZ")-$$"
OUT_DIR="$ROOT/runs/api/$TURN_ID"
RESPONSE_PATH="$OUT_DIR/response.json"
SYSTEM_CONTEXT_PATH="$OUT_DIR/system_context.json"
PROMPT_PATH="$OUT_DIR/inference_prompt.txt"
INFERENCE_PATH="$OUT_DIR/inference.json"

mkdir -p "$OUT_DIR"
"$ROOT/api/build_system_context.sh" "$SYSTEM_CONTEXT_PATH" >/dev/null

INPUT_LOWER="$(printf '%s' "$USER_INPUT" | tr '[:upper:]' '[:lower:]')"
CONTINUITY_PROVIDER_SCRIPT="$ROOT/scripts/continuity_provider.sh"

ANSWER_TEXT=""
ABSTAINED=false
INFERENCE_AVAILABLE=false
INFERENCE_RESULT_JSON='null'
PACKET_POINTER_PATH=""
PACKET_REGISTRY_PATH=""
PACKET_CONTEXT_JSON='null'
TENSOR_STRONGEST_SOURCE_OVERRIDE=""
TENSOR_DOMINANT_STAGE_OVERRIDE=""
TENSOR_WEAKEST_METRIC_OVERRIDE=""
TENSOR_FRONTIER_READ_OVERRIDE=""

latest_runtime_artifact_graph() {
  find "$ROOT/runs/runtime" -name graph_state.json -type f 2>/dev/null | sort | while read -r graph; do
    if jq -e '.effects[]? | select((.path // "") != "")' "$graph" >/dev/null; then
      printf '%s\n' "$graph"
    fi
  done | tail -n 1
}

latest_continuity_pointer() {
  if [ -f "$ROOT/runs/continuity/latest.json" ]; then
    printf '%s\n' "$ROOT/runs/continuity/latest.json"
  fi
}

continuity_provider_status() {
  if [ -x "$CONTINUITY_PROVIDER_SCRIPT" ]; then
    "$CONTINUITY_PROVIDER_SCRIPT" status 2>/dev/null || true
  fi
}

continuity_provider_surfaces() {
  if [ -x "$CONTINUITY_PROVIDER_SCRIPT" ]; then
    "$CONTINUITY_PROVIDER_SCRIPT" surfaces 2>/dev/null || true
  fi
}

continuity_provider_lineage() {
  local version_id="$1"
  if [ -x "$CONTINUITY_PROVIDER_SCRIPT" ]; then
    "$CONTINUITY_PROVIDER_SCRIPT" lineage "$version_id" 2>/dev/null || true
  fi
}

continuity_resume_packet() {
  if [ -x "$ROOT/scripts/render_continuity_flow.sh" ]; then
    "$ROOT/scripts/render_continuity_flow.sh" "$1" 2>/dev/null || true
  fi
}

resolve_path_from_root() {
  local candidate="$1"
  case "$candidate" in
    "")
      printf '%s' ""
      ;;
    /*)
      printf '%s' "$candidate"
      ;;
    *)
      printf '%s' "$ROOT/$candidate"
      ;;
  esac
}

load_packet_context() {
  local packet_enabled latest_pointer registry_path
  packet_enabled="$(yq -r '.packet_context.enabled // false' "$INFERENCE_CONFIG_PATH")"
  if [ "$packet_enabled" != "true" ]; then
    return 1
  fi

  latest_pointer="$(yq -r '.packet_context.latest_pointer_path // ""' "$INFERENCE_CONFIG_PATH")"
  PACKET_POINTER_PATH="$(resolve_path_from_root "$latest_pointer")"
  if [ ! -f "$PACKET_POINTER_PATH" ]; then
    return 1
  fi

  registry_path="$(jq -r '.registry_path // empty' "$PACKET_POINTER_PATH")"
  PACKET_REGISTRY_PATH="$(resolve_path_from_root "$registry_path")"
  if [ ! -f "$PACKET_REGISTRY_PATH" ]; then
    return 1
  fi

  PACKET_CONTEXT_JSON="$(jq -c '{generated_at, packet_count, abstraction_ids, packets: [.packets[] | {abstraction_id, observer_basis, bits, tensor_slice}]}' "$PACKET_REGISTRY_PATH")"
  return 0
}

handle_exact_query() {
  if printf '%s' "$INPUT_LOWER" | grep -Eq 'continuity'; then
    local continuity_status continuity_surfaces_json continuity_lineage_json continuity_version continuity_predecessor continuity_lineage continuity_surfaces continuity_default_surface continuity_provider continuity_surface_count continuity_resume_json continuity_resume_command
    continuity_status="$(continuity_provider_status)"
    continuity_provider="$(printf '%s' "$continuity_status" | jq -r '.provider // "unknown"' 2>/dev/null || printf '%s' "unknown")"
    if printf '%s' "$continuity_status" | jq -e '.available == true or (.items | length) > 0' >/dev/null 2>&1; then
      if printf '%s' "$continuity_status" | jq -e '.items' >/dev/null 2>&1; then
        continuity_version="$(printf '%s' "$continuity_status" | jq -r '.items[0].version_id // empty')"
        continuity_predecessor="$(printf '%s' "$continuity_status" | jq -r '.items[0].predecessor // ""')"
      else
        continuity_version="$(printf '%s' "$continuity_status" | jq -r '.continuity_version_id // empty')"
        continuity_predecessor="$(printf '%s' "$continuity_status" | jq -r '.predecessor_id // ""')"
      fi
      continuity_default_surface=""
      continuity_lineage=""
      continuity_surfaces=""
      continuity_resume_json=""
      if [ -n "$continuity_version" ] && printf '%s' "$INPUT_LOWER" | grep -Eq 'lineage|predecessor|ancestor'; then
        continuity_lineage_json="$(continuity_provider_lineage "$continuity_version")"
        continuity_lineage="$(printf '%s' "$continuity_lineage_json" | jq -r '.graph_id // .manifest_path // .lineage_path // ""' 2>/dev/null || true)"
      fi
      if printf '%s' "$INPUT_LOWER" | grep -Eq 'resume|desk|next move|continue'; then
        continuity_resume_json="$(continuity_resume_packet "$continuity_version")"
        continuity_default_surface="$(printf '%s' "$continuity_resume_json" | jq -r '.context.active_surface // .action.recommended_surface // ""' 2>/dev/null || true)"
        continuity_resume_command="$(printf '%s' "$continuity_resume_json" | jq -r '.action.resume_packet.command // ""' 2>/dev/null || true)"
        DECISION_BRIEF="Answered from the deterministic kernel using the provider-first continuity resume desk."
        ANSWER_TEXT="Resume continuity from $continuity_version on surface $continuity_default_surface. The next desk command is $continuity_resume_command."
      elif printf '%s' "$INPUT_LOWER" | grep -Eq 'surface|resume|picker'; then
        continuity_surfaces_json="$(continuity_provider_surfaces)"
        continuity_surfaces="$(printf '%s' "$continuity_surfaces_json" | jq -r '[.items[].surface_id] | join(", ")' 2>/dev/null || true)"
        continuity_surface_count="$(printf '%s' "$continuity_surfaces_json" | jq -r '(.items | length)' 2>/dev/null || printf '%s' "0")"
        continuity_default_surface="$(printf '%s' "$continuity_surfaces_json" | jq -r '.items[] | select(.activated == true) | .surface_id' 2>/dev/null | head -n 1)"
        if [ -z "$continuity_default_surface" ]; then
          continuity_default_surface="$(printf '%s' "$continuity_surfaces_json" | jq -r '.items[0].surface_id // ""' 2>/dev/null || true)"
        fi
        DECISION_BRIEF="Answered from the deterministic kernel using the provider-first continuity surface registry."
        ANSWER_TEXT="The active continuity version is $continuity_version. Its materialized surfaces are $continuity_surfaces, with default surface $continuity_default_surface, from provider $continuity_provider."
      elif printf '%s' "$INPUT_LOWER" | grep -Eq 'lineage|predecessor|ancestor'; then
        DECISION_BRIEF="Answered from the deterministic kernel using the provider-first continuity lineage slice."
        ANSWER_TEXT="The active continuity version is $continuity_version, derived from $continuity_predecessor. Its lineage state is recorded at $continuity_lineage through provider $continuity_provider."
      else
        DECISION_BRIEF="Answered from the deterministic kernel using the provider-first continuity status surface."
        ANSWER_TEXT="The active continuity slice is $continuity_version, derived from $continuity_predecessor, from provider $continuity_provider."
      fi
      ABSTAINED=false
    else
      DECISION_BRIEF="Abstained because no continuity slice has been materialized yet."
      ANSWER_TEXT="I do not know. No continuity slice has been materialized yet."
      ABSTAINED=true
    fi
    TENSOR_STRONGEST_SOURCE_OVERRIDE="receipt_state"
    TENSOR_DOMINANT_STAGE_OVERRIDE="select"
    TENSOR_WEAKEST_METRIC_OVERRIDE="promotion_readiness"
    TENSOR_FRONTIER_READ_OVERRIDE="deterministic_exact_lookup"
    return 0
  fi

  if printf '%s' "$INPUT_LOWER" | grep -Eq 'weekly schedule|schedule|calendar'; then
    DECISION_BRIEF="Answered from the deterministic kernel because no supported weekly schedule exists in current graph state."
    ANSWER_TEXT="I do not know. No weekly schedule is present in the current graph state."
    ABSTAINED=true
    TENSOR_STRONGEST_SOURCE_OVERRIDE="graph_state"
    TENSOR_DOMINANT_STAGE_OVERRIDE="select"
    TENSOR_WEAKEST_METRIC_OVERRIDE="promotion_readiness"
    TENSOR_FRONTIER_READ_OVERRIDE="deterministic_exact_lookup"
    return 0
  fi

  if printf '%s' "$INPUT_LOWER" | grep -Eq 'freshest|latest|most recent'; then
    local latest_graph latest_receipt latest_effect_path
    latest_graph="$(latest_runtime_artifact_graph)"
    if [ -n "$latest_graph" ] && [ -f "$latest_graph" ]; then
      latest_receipt="$(jq -r '.receipt' "$latest_graph")"
      latest_effect_path="$(jq -r '[.effects[]? | select((.path // "") != "")][0].path // empty' "$latest_graph")"
      DECISION_BRIEF="Answered from the deterministic kernel using the latest receipt-backed runtime artifact."
      ANSWER_TEXT="The freshest runtime artifact is $latest_effect_path from receipt $latest_receipt."
      ABSTAINED=false
    else
      DECISION_BRIEF="Abstained because no receipt-backed runtime state exists yet."
      ANSWER_TEXT="I do not know. No receipt-backed runtime state exists yet."
      ABSTAINED=true
    fi
    TENSOR_STRONGEST_SOURCE_OVERRIDE="receipt_state"
    TENSOR_DOMINANT_STAGE_OVERRIDE="select"
    TENSOR_WEAKEST_METRIC_OVERRIDE="promotion_readiness"
    TENSOR_FRONTIER_READ_OVERRIDE="deterministic_exact_lookup"
    return 0
  fi

  return 1
}

run_codex_inference() {
  local backend_id provider enabled command_name model sandbox ephemeral skip_git use_chatgpt
  local system_context_compact policy_context_compact packet_bits packet_tensor
  local -a codex_cmd

  backend_id="$(yq -r '.default_backend' "$INFERENCE_CONFIG_PATH")"
  enabled="$(yq -r ".backends.\"$backend_id\".enabled" "$INFERENCE_CONFIG_PATH")"
  if [ "$enabled" != "true" ]; then
    return 1
  fi

  provider="$(yq -r ".backends.\"$backend_id\".provider" "$INFERENCE_CONFIG_PATH")"
  command_name="$(yq -r ".backends.\"$backend_id\".command" "$INFERENCE_CONFIG_PATH")"
  model="$(yq -r ".backends.\"$backend_id\".model" "$INFERENCE_CONFIG_PATH")"
  sandbox="$(yq -r ".backends.\"$backend_id\".sandbox" "$INFERENCE_CONFIG_PATH")"
  ephemeral="$(yq -r ".backends.\"$backend_id\".ephemeral" "$INFERENCE_CONFIG_PATH")"
  skip_git="$(yq -r ".backends.\"$backend_id\".skip_git_repo_check" "$INFERENCE_CONFIG_PATH")"
  use_chatgpt="$(yq -r ".backends.\"$backend_id\".use_chatgpt_subscription" "$INFERENCE_CONFIG_PATH")"
  packet_bits="$(yq -r '.packet_context.reread_on_bits | join(", ")' "$INFERENCE_CONFIG_PATH" 2>/dev/null || true)"
  packet_tensor="$(yq -r '.packet_context.reread_on_tensor | join(", ")' "$INFERENCE_CONFIG_PATH" 2>/dev/null || true)"
  system_context_compact="$(jq -c '{current_position, runtime_contract, latest_runtime_state, agent_bootstrap}' "$SYSTEM_CONTEXT_PATH")"
  policy_context_compact="$(jq -c '{bits, vectors, tensors, invariants}' "$ROOT/policy/control_language_v0.json")"

  cat > "$PROMPT_PATH" <<EOF
You are the inference backend for bit_vector_tensor_control_policy.
Work as the reasoning engine under the deterministic turn kernel.
Do not execute code, write files, or open an execution lane.
The runtime kernel owns lane choice; assume graph-first memory mode unless the runtime explicitly opens execution elsewhere.
Abstain plainly when the ask depends on missing or unsupported state.
Keep \`answer_text\` concise and user-facing.
Keep \`decision_brief\` to one sentence.
Return JSON only matching the provided schema.

System context:
$system_context_compact

Policy context:
$policy_context_compact

Packet context:
$PACKET_CONTEXT_JSON

Packet-first rule:
Reason over packet state before reopening raw evidence.
Reopen raw evidence only when packet bits among [$packet_bits] indicate it or packet tensor metrics among [$packet_tensor] are non-zero or unresolved.

User ask: $USER_INPUT
EOF

  codex_cmd=("$command_name" "exec" "-m" "$model" "-s" "$sandbox" "-C" "$ROOT" "--output-schema" "$INFERENCE_SCHEMA_PATH" "-o" "$INFERENCE_PATH" "-")
  if [ "$ephemeral" = "true" ]; then
    codex_cmd+=("--ephemeral")
  fi
  if [ "$skip_git" = "true" ]; then
    codex_cmd+=("--skip-git-repo-check")
  fi

  if ! "${codex_cmd[@]}" < "$PROMPT_PATH" >/dev/null 2>"$OUT_DIR/inference.stderr"; then
    return 1
  fi

  jq \
    --arg id "$backend_id" \
    --arg provider "$provider" \
    --arg model "$model" \
    --arg sandbox "$sandbox" \
    --argjson uses_chatgpt_subscription "$use_chatgpt" \
    '. + {
      backend: {
        id: $id,
        provider: $provider,
        model: $model,
        sandbox: $sandbox,
        uses_chatgpt_subscription: $uses_chatgpt_subscription
      }
    }' "$INFERENCE_PATH" > "$INFERENCE_PATH.tmp"
  mv "$INFERENCE_PATH.tmp" "$INFERENCE_PATH"
}

if [ -n "$MANIFEST_PATH" ]; then
  EXEC_OUTPUT="$("$ROOT/runtime/execute_manifest.sh" "$MANIFEST_PATH")"
  RECEIPT_PATH="$(printf '%s\n' "$EXEC_OUTPUT" | sed -n '1p')"
  SUMMARY_PATH="$(printf '%s\n' "$EXEC_OUTPUT" | sed -n '2p')"
  LANE="execution"
  EXEC_ALLOWED=true
  DECISION_BRIEF="Executed bounded manifest and emitted receipt-backed result."
  UI_MODE="confirm"
  UI_LAYOUT="chat_with_sidecar"
  ANSWER_TEXT="Executed bounded manifest and emitted receipt-backed result."
else
  RECEIPT_PATH=""
  SUMMARY_PATH=""
  EXEC_ALLOWED=false
  LANE="memory"
  UI_MODE="chat"
  UI_LAYOUT="chat_only"

  if [ -f "$INFERENCE_CONFIG_PATH" ]; then
    load_packet_context || true
  fi

  if handle_exact_query; then
    :
  elif [ -f "$INFERENCE_CONFIG_PATH" ] && run_codex_inference; then
    INFERENCE_AVAILABLE=true
    INFERENCE_RESULT_JSON="$(cat "$INFERENCE_PATH")"
    DECISION_BRIEF="$(jq -r '.decision_brief' "$INFERENCE_PATH")"
    ANSWER_TEXT="$(jq -r '.answer_text' "$INFERENCE_PATH")"
    ABSTAINED="$(jq -r '.abstained' "$INFERENCE_PATH")"
  else
    DECISION_BRIEF="Stayed in graph-first reasoning mode; no execution lane opened."
    ANSWER_TEXT="The current runtime stays graph-first until a bounded execution task is selected."
  fi
fi

jq -n \
  --slurpfile system_context "$SYSTEM_CONTEXT_PATH" \
  --arg user_input "$USER_INPUT" \
  --arg lane "$LANE" \
  --arg decision_brief "$DECISION_BRIEF" \
  --arg answer_text "$ANSWER_TEXT" \
  --arg receipt_path "$RECEIPT_PATH" \
  --arg summary_path "$SUMMARY_PATH" \
  --arg ui_mode "$UI_MODE" \
  --arg ui_layout "$UI_LAYOUT" \
  --arg inference_path "$INFERENCE_PATH" \
  --arg inference_config_path "$INFERENCE_CONFIG_PATH" \
  --arg inference_error_path "$OUT_DIR/inference.stderr" \
  --arg packet_pointer_path "$PACKET_POINTER_PATH" \
  --arg packet_registry_path "$PACKET_REGISTRY_PATH" \
  --arg tensor_strongest_source_override "$TENSOR_STRONGEST_SOURCE_OVERRIDE" \
  --arg tensor_dominant_stage_override "$TENSOR_DOMINANT_STAGE_OVERRIDE" \
  --arg tensor_weakest_metric_override "$TENSOR_WEAKEST_METRIC_OVERRIDE" \
  --arg tensor_frontier_read_override "$TENSOR_FRONTIER_READ_OVERRIDE" \
  --argjson inference_result "$INFERENCE_RESULT_JSON" \
  --argjson execution_allowed "$EXEC_ALLOWED" \
  --argjson abstained "$ABSTAINED" \
  --argjson inference_available "$INFERENCE_AVAILABLE" \
  '{
    user_input:$user_input,
    lane:$lane,
    control_vector:(if $execution_allowed then
      {plan:0.7, execute:0.8, review:0.6, promote:0.2}
    elif $lane == "audit" then
      {plan:0.5, execute:0.0, review:0.9, promote:0.4}
    elif $lane == "tooling" then
      {plan:0.6, execute:0.0, review:0.5, promote:0.3}
    else
      {plan:0.7, execute:0.1, review:0.6, promote:0.2}
    end),
    tensor_surface:{
      strongest_source:(if $tensor_strongest_source_override != "" then $tensor_strongest_source_override elif $execution_allowed then "receipt_state" elif $lane == "audit" then "receipts" elif $lane == "tooling" then "external_tools" elif ($packet_registry_path | length) > 0 then "graph_state" else "graph_state" end),
      dominant_stage:(if $tensor_dominant_stage_override != "" then $tensor_dominant_stage_override elif $execution_allowed then "execute" elif $lane == "audit" then "review" elif $lane == "tooling" then "select" else "discover" end),
      weakest_metric:(if $tensor_weakest_metric_override != "" then $tensor_weakest_metric_override elif $execution_allowed then "promotion_readiness" elif $lane == "audit" then "latency" else "promotion_readiness" end),
      frontier_read:(if $tensor_frontier_read_override != "" then $tensor_frontier_read_override elif $execution_allowed then "bounded_execution_with_receipt" elif $inference_available and ($packet_registry_path | length) > 0 then "corpus_packet_first_reasoning" elif $inference_available then "codex_cli_graph_first_reasoning" else "graph_first_reasoning" end)
    },
    execution_gate:{allowed:$execution_allowed},
    receipt_requirements:{minimum_receipts:(if $execution_allowed then 1 else 0 end)},
    ui_projection:{
      mode:$ui_mode,
      layout:$ui_layout,
      components:(if $execution_allowed
        then ["chat_thread","proposal_card","receipt_panel"]
        else ["chat_thread","next_step_card"]
      end)
    },
    answer_text:$answer_text,
    abstained:$abstained,
    decision_brief:$decision_brief,
    inference:(if $inference_available and ($inference_path | length) > 0
      then {
        config_path:$inference_config_path,
        output_path:$inference_path,
        backend:$inference_result.backend,
        packet_pointer_path:(if $packet_pointer_path == "" then null else $packet_pointer_path end),
        packet_registry_path:(if $packet_registry_path == "" then null else $packet_registry_path end)
      }
      else {
        config_path:(if $inference_config_path == "" then null else $inference_config_path end),
        output_path:(if $inference_path == "" then null else $inference_path end),
        error_path:(if $inference_error_path == "" then null else $inference_error_path end),
        packet_pointer_path:(if $packet_pointer_path == "" then null else $packet_pointer_path end),
        packet_registry_path:(if $packet_registry_path == "" then null else $packet_registry_path end)
      }
    end),
    system_context:$system_context[0],
    receipt_path:(if $receipt_path == "" then null else $receipt_path end),
    runtime_summary:(if $summary_path == "" then null else $summary_path end)
  }' > "$RESPONSE_PATH"

printf '%s\n' "$RESPONSE_PATH"