docs(dark-factory): Autonomous Agent Coding Pattern design

.github/workflows/dark-factory.yml

@@ -0,0 +1,77 @@
+# Dark Factory (Flow B) trigger — issue labeled `dark-factory` → orchestrator.
+#
+# This is the P1 entrypoint (§4 step 1). It gates on the label, mints a
+# short-TTL token scoped to this repo, and POSTs the run request to the
+# orchestrator running on spoke-dev. The orchestrator (not this Action) holds
+# the long-lived credentials and drives the sandbox; the Action's only job is
+# to authenticate the trigger and hand over a short-lived token.
+#
+# The token here is the workflow's GITHUB_TOKEN (auto-expires when the run
+# ends). For cross-repo / org installs, swap in a GitHub App token minted via
+# actions/create-github-app-token — the orchestrator treats it the same way.
+name: dark-factory
+
+on:
+  issues:
+    types: [labeled]
+
+# Least-privilege: the orchestrator opens the PR + updates the sticky comment
+# using the token we pass, so it needs write on contents + PRs + issues.
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+
+jobs:
+  dispatch:
+    # Only fire when the `dark-factory` label is the one that was added.
+    if: github.event.label.name == 'dark-factory'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Acknowledge on the issue
+        uses: actions/github-script@v7
+        with:
+          script: |
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body: '🏭 Dark Factory accepted this issue — claiming a warm Kata sandbox on the hub…',
+            });
+
+      - name: Submit df-run to Argo Workflows
+        env:
+          # argo-server events endpoint base, e.g. https://<argo-host>/argo-workflows
+          # Configure as a repo/org variable so the host isn't hard-coded.
+          ARGO_SERVER: ${{ vars.DARK_FACTORY_ARGO_SERVER }}
+          # Bearer token for the argo-server events API (a token bound to the
+          # dark-factory-workflow SA, or an SSO token). Stored as a repo secret.
+          ARGO_TOKEN: ${{ secrets.DARK_FACTORY_ARGO_TOKEN }}
+          ISSUE_ID: ${{ github.event.issue.id }}
+          ISSUE_NUMBER: ${{ github.event.issue.number }}
+          ISSUE_TITLE: ${{ github.event.issue.title }}
+          ISSUE_BODY: ${{ github.event.issue.body }}
+          REPO: ${{ github.repository }}
+          BASE: ${{ github.event.repository.default_branch }}
+        run: |
+          set -euo pipefail
+          if [ -z "${ARGO_SERVER:-}" ]; then
+            echo "::error::DARK_FACTORY_ARGO_SERVER is not set — cannot submit."
+            exit 1
+          fi
+          # POST the issue to the WorkflowEventBinding 'dark-factory' in the argo
+          # namespace. The discriminator header + payload.issue selector gate it.
+          payload="$(jq -n \
+            --arg id "$ISSUE_ID" \
+            --arg number "$ISSUE_NUMBER" \
+            --arg repo "$REPO" \
+            --arg title "$ISSUE_TITLE" \
+            --arg body "$ISSUE_BODY" \
+            --arg base "$BASE" \
+            '{issue: {id: $id, number: ($number|tonumber), repo: $repo, title: $title, body: $body, base: $base}}')"
+          curl -fsS -X POST "${ARGO_SERVER}/api/v1/events/argo/dark-factory" \
+            -H "Content-Type: application/json" \
+            -H "x-dark-factory: true" \
+            -H "Authorization: Bearer ${ARGO_TOKEN}" \
+            -d "$payload"
+          echo "Submitted df-run for issue #$ISSUE_NUMBER to Argo Workflows."

.gitignore

@@ -2,3 +2,10 @@
 config.local.yaml
 private/
 .local/
+
+# Dark Factory IAM terraform working files (committed: iam/*.tf; ignored: state/plugins)
+gitops/addons/charts/dark-factory/iam/.terraform/
+gitops/addons/charts/dark-factory/iam/.terraform.lock.hcl
+gitops/addons/charts/dark-factory/iam/terraform.tfstate
+gitops/addons/charts/dark-factory/iam/terraform.tfstate.backup
+gitops/addons/charts/dark-factory/iam/_provider.tf

applications/strands-agent-base/app/agent.py

@@ -47,6 +47,25 @@ def _get_model() -> OpenAIModel:
     return _model
 
 
+def _gateway_headers() -> dict:
+    """Authorization header from the projected workload-identity token.
+
+    The `gateway-identity` OAM trait mounts a projected ServiceAccount token
+    (audience `agentgateway`) and sets WORKLOAD_TOKEN_PATH. AgentGateway
+    validates it against the cluster OIDC issuer. Read fresh on each connect so
+    the kubelet-rotated token is always current. Returns {} when no token is
+    mounted (gateway auth not in use).
+    """
+    path = os.getenv("WORKLOAD_TOKEN_PATH")
+    if path:
+        try:
+            with open(path) as f:
+                return {"Authorization": "Bearer " + f.read().strip()}
+        except OSError:
+            logger.warning("WORKLOAD_TOKEN_PATH set but token unreadable at %s", path)
+    return {}
+
+
 def _get_mcp_tools() -> list:
     global _mcp_tools, _mcp_exit_stack
     if _mcp_exit_stack is not None:
@@ -61,7 +80,7 @@ def _get_mcp_tools() -> list:
     for url in urls:
         logger.info(f"Connecting to MCP server: {url}")
         try:
-            client = MCPClient(lambda u=url: streamablehttp_client(u))
+            client = MCPClient(lambda u=url: streamablehttp_client(u, headers=_gateway_headers()))
             stack.enter_context(client)
             server_tools = client.list_tools_sync()
             logger.info(f"  Loaded {len(server_tools)} tools from {url}")

applications/strands-agent-base/app/main.py

@@ -20,8 +20,6 @@
 # 3. Via Collector (OTEL_EXPORTER_OTLP_ENDPOINT set) — agent sends to local collector
 if os.getenv("OTEL_PYTHON_DISTRO") == "aws_distro":
     # Decentralized mode: ADOT auto-instrumentation handles telemetry.
-    # No manual StrandsTelemetry init — the aws_distro entry point
-    # configures exporters via env vars (CW Logs, X-Ray, CW Metrics).
     pass
 elif os.getenv("LANGFUSE_BASE_URL"):
     try: