{"slug":"architecture/TWIN_ORCHESTRATOR_DEPLOYMENT","title":"Twin Orchestrator Deployment","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/TWIN_ORCHESTRATOR_DEPLOYMENT.mdx","bytes":10467,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> **Date:** 2026-06-09  \n> **Status:** READY FOR DEPLOYMENT  \n> **Phase:** 3 - Cognitive Orchestration Layer\n\n---\n\n## What Is This\n\nThe **Twin Orchestrator** is the cognitive orchestration layer that transforms the Twin from a chat interface into an always-on reasoning system.\n\n**This is NOT:**\n\n- An AI infrastructure worker\n- A model gateway\n- A RAG engine\n- An inference service\n\n**This IS:**\n\n- A reasoning layer (What should happen next?)\n- A coordination layer (Observe → Reason → Propose → Dispatch)\n- A continuity layer (Persistent state across sessions)\n- A planning layer (Strategic oversight)\n\n---\n\n## Architecture Clarity\n\n### Infrastructure Layer (Workers)\n\n```\nIntelligence Worker\n├─ AI Router (Workers AI → OpenRouter)\n├─ RAG Engine (AI Search)\n└─ Model Management\n\nPipeline Worker\n├─ Entity Resolution\n├─ Spine Writer\n└─ Normalization\n\nKnowledge Worker\n├─ Document Ingestion\n├─ Search Indexing\n└─ Publication\n```\n\n**These provide tools. They don't make decisions.**\n\n---\n\n### Cognitive Layer (Twin)\n\n```\nTwin Orchestrator\n│\n├─ OBSERVE (every 5 minutes)\n│  ├─ Memory state\n│  ├─ Pending signals\n│  ├─ Pending proposals\n│  ├─ Queue health\n│  └─ Staleness checks\n│\n├─ REASON (via Intelligence AI)\n│  ├─ What should happen next?\n│  ├─ What's at risk?\n│  ├─ What's overdue?\n│  └─ What needs attention?\n│\n├─ PROPOSE (structured suggestions)\n│  ├─ Create proposals\n│  ├─ Attach reasoning\n│  ├─ Estimate impact/risk\n│  └─ Route to governance\n│\n├─ COORDINATE (approved actions)\n│  ├─ Dispatch to Act service\n│  ├─ Monitor execution\n│  └─ Handle failures\n│\n└─ LEARN (via Triage Bot)\n   └─ Propose memory updates\n```\n\n**The Twin orchestrates. It does not execute.**\n\n---\n\n## Implementation\n\n### Files Created\n\n1. **`services/twin-orchestrator/wrangler.toml`**\n   - Scheduled trigger: every 5 minutes\n   - Service bindings: MCP, Intelligence, Pipeline, Knowledge, Continuity\n   - Workflows: MorningBrief, Signal, Act\n\n2. **`services/twin-orchestrator/src/index.ts`**\n   - `scheduled()` — Twin observe loop\n   - `buildTwinContext()` — Query all systems via MCP\n   - `reasonAboutContext()` — Call Intelligence AI for reasoning\n   - `generateProposals()` — Create structured proposals\n   - `coordinateApprovedActions()` — Dispatch approved actions\n   - `monitorOutcomes()` — Track execution status\n\n3. **`services/twin-orchestrator/package.json`**\n   - Dependencies: Hono (HTTP framework)\n\n4. **`docs/tech/TWIN_AS_COGNITIVE_ORCHESTRATOR.md`**\n   - Canonical architecture doc\n   - Clarifies Twin vs Infrastructure separation\n\n---\n\n## How It Works\n\n### 1. Scheduled Observe Loop (Every 5 Minutes)\n\n```typescript\nexport async function scheduled(event: ScheduledEvent, env: Env) {\n  const context = await buildTwinContext(env, tenantId);\n  const reasoning = await reasonAboutContext(env, context, tenantId);\n  const proposals = await generateProposals(env, reasoning, tenantId);\n  await coordinateApprovedActions(env, tenantId);\n  await monitorOutcomes(env, tenantId);\n}\n```\n\n---\n\n### 2. Build Context (Observe)\n\nQueries via service bindings:\n\n```typescript\n// Memory via MCP\nconst memory = await env.MCP_CONNECTOR.fetch(\"/v1/memory/org-search\");\n\n// Signals via MCP\nconst signals = await env.MCP_CONNECTOR.fetch(\"/v1/signals/list\");\n\n// Proposals via MCP\nconst proposals = await env.MCP_CONNECTOR.fetch(\"/v1/proposals/list\");\n\n// Operations health\nconst health = await env.PIPELINE.fetch(\"/health\");\n```\n\n**Result:** Complete system state snapshot\n\n---\n\n### 3. Reason About Context (Think)\n\nUses Intelligence worker's AI router:\n\n```typescript\nconst response = await env.INTELLIGENCE.fetch(\"/v1/test/rag\", {\n  method: \"POST\",\n  body: JSON.stringify({\n    question: `Analyze this context and suggest actions: ${JSON.stringify(context)}`,\n    tier: \"balanced\", // OpenRouter or Workers AI\n  }),\n});\n```\n\n**Result:** Structured reasoning with suggested actions\n\n---\n\n### 4. Generate Proposals (Suggest)\n\nCreates proposals for human approval:\n\n```typescript\nfor (const action of reasoning.suggested_actions) {\n  await env.MCP_CONNECTOR.fetch(\"/v1/proposals/create\", {\n    method: \"POST\",\n    body: JSON.stringify({\n      type: action.type,\n      reasoning: action.reasoning,\n      impact: action.impact,\n      risk: action.risk,\n      requires_approval: true,\n    }),\n  });\n}\n```\n\n**Result:** Proposals awaiting HITL approval\n\n---\n\n### 5. Coordinate Actions (Dispatch)\n\nFor approved proposals:\n\n```typescript\nconst approved = await env.MCP_CONNECTOR.fetch(\"/v1/proposals/list?status=approved\");\n\nfor (const proposal of approved) {\n  // Dispatch to Act service (via Intelligence worker)\n  await env.INTELLIGENCE.fetch(\"/v1/act/execute\", {\n    method: \"POST\",\n    body: JSON.stringify({ proposal_id: proposal.id }),\n  });\n}\n```\n\n**Result:** Actions dispatched for execution\n\n---\n\n### 6. Monitor Outcomes (Track)\n\nCheck execution status:\n\n```typescript\n// Query D1 for action execution records\nconst executions = await env.D1.prepare(\"SELECT * FROM action_executions WHERE status = ? LIMIT 10\")\n  .bind(\"running\")\n  .all();\n\n// Alert on failures\nfor (const exec of executions.results) {\n  if (exec.status === \"failed\") {\n    // Create proposal for retry or escalation\n  }\n}\n```\n\n**Result:** Continuous monitoring + failure handling\n\n---\n\n## Deployment\n\n### Step 1: Install Dependencies\n\n```bash\ncd services/twin-orchestrator\nnpm install\n```\n\n### Step 2: Deploy\n\n```bash\nunset CLOUDFLARE_API_TOKEN\nwrangler deploy --env=\"\"\n```\n\n### Step 3: Verify\n\n```bash\n# Check health\ncurl https://twin.dev.integratewise.ai/health\n\n# Manual observe trigger (for testing)\ncurl -X POST https://twin.dev.integratewise.ai/v1/twin/observe \\\n  -H \"x-tenant-id: iw-customer-zero\"\n```\n\n### Step 4: Monitor Logs\n\n```bash\nwrangler tail twin-orchestrator\n```\n\n**Expected output every 5 minutes:**\n\n```\n[Twin Orchestrator] Scheduled trigger: */5 * * * *\n[Twin] Context built: { memory_items: 10, signals: 3, proposals: 2 }\n[Twin] Reasoning complete: { observations: 4, concerns: 1, suggested_actions: 1 }\n[Twin] Proposals created: 1\n[Twin] Observe loop complete\n```\n\n---\n\n## Integration Points\n\n### Twin → MCP Connector\n\n**Twin queries system state via MCP tools:**\n\n- `memory.search_org` — Recent org memory\n- `signal.list` — Pending signals\n- `proposal.list` — Pending/approved proposals\n- `proposal.create` — Create new proposal\n\n**MCP Connector provides:**\n\n- 18 tools (memory, spine, signal, proposal, search)\n- OAuth authentication\n- Tenant isolation\n- Rate limiting\n\n---\n\n### Twin → Intelligence Worker\n\n**Twin uses Intelligence for reasoning:**\n\n- `/v1/test/rag` — RAG-enabled AI query\n- AI router (Workers AI → OpenRouter → Fusion)\n- Multi-tier fallback\n- Source attribution\n\n**Intelligence Worker provides:**\n\n- AI inference\n- RAG search\n- Model routing\n- Token management\n\n---\n\n### Twin → Pipeline Worker\n\n**Twin queries Spine state:**\n\n- `/v1/spine/recent-changes` — Entity changes\n- `/health` — Worker status\n\n**Pipeline Worker provides:**\n\n- Spine read access\n- Entity resolution\n- Relationship graph\n\n---\n\n### Twin → Continuity Worker\n\n**Twin manages session state:**\n\n- `/v1/continuity/sessions` — Active sessions\n- `/v1/continuity/checkpoints` — Resume points\n\n**Continuity Worker provides:**\n\n- Session persistence\n- Checkpoint/resume\n- TTL cleanup\n\n---\n\n## Phase 3 Roadmap\n\n### Week 1: Foundation\n\n- ✅ Create Twin Orchestrator worker\n- ✅ Implement observe loop\n- ✅ Wire MCP tools\n- ✅ Implement basic reasoning\n- ⏳ Deploy + test\n- ⏳ Monitor for 48 hours\n\n### Week 2: Enhancement\n\n- ⏳ Improve reasoning (structured output)\n- ⏳ Add staleness checks\n- ⏳ Add commitment tracking\n- ⏳ Wire Action coordination\n- ⏳ Wire Outcome monitoring\n\n### Week 3: Workflows\n\n- ⏳ Implement MorningBriefWorkflow\n- ⏳ Implement SignalWorkflow\n- ⏳ Implement ActWorkflow\n- ⏳ Test durable execution\n\n### Week 4: Production\n\n- ⏳ Multi-tenant support\n- ⏳ Custom observe intervals per tenant\n- ⏳ User-configurable reasoning rules\n- ⏳ Dashboard for Twin activity\n\n---\n\n## Success Criteria\n\n### Twin is a Cognitive Orchestrator When:\n\n- ✅ Runs on schedule (every 5 minutes)\n- ✅ Observes system state via MCP\n- ✅ Reasons via Intelligence AI\n- ✅ Creates proposals (not decisions)\n- ⏳ Coordinates approved actions\n- ⏳ Monitors execution outcomes\n- ⏳ Maintains continuity across sessions\n- ⏳ Learns from outcomes (via Triage Bot)\n\n---\n\n## Key Differences from Intelligence Worker\n\n| Aspect        | Intelligence Worker      | Twin Orchestrator          |\n| ------------- | ------------------------ | -------------------------- |\n| **Purpose**   | AI Infrastructure        | Cognitive Orchestration    |\n| **Role**      | Tool Provider            | Strategic Reasoner         |\n| **Triggers**  | Queues, HTTP requests    | Schedule, events           |\n| **Outputs**   | AI responses, embeddings | Proposals, coordination    |\n| **Writes to** | D1 cache, queues         | Proposals table            |\n| **Approves**  | Nothing                  | Nothing (proposes only)    |\n| **Executes**  | AI inference             | Nothing (coordinates only) |\n| **State**     | Stateless per request    | Stateful across time       |\n\n---\n\n## Testing\n\n### Manual Trigger\n\n```bash\ncurl -X POST https://twin.dev.integratewise.ai/v1/twin/observe \\\n  -H \"x-tenant-id: iw-customer-zero\"\n```\n\n**Expected response:**\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"context\": {\n      \"memory\": { \"recent\": [...], \"pending_reviews\": [] },\n      \"signals\": { \"unprocessed\": [...], \"high_priority\": [...] },\n      \"proposals\": { \"pending_approval\": [...] }\n    },\n    \"reasoning\": {\n      \"observations\": [...],\n      \"concerns\": [...],\n      \"suggested_actions\": [...]\n    },\n    \"proposals\": [...]\n  }\n}\n```\n\n---\n\n## Next Steps\n\n1. ✅ Deploy Twin Orchestrator\n2. ⏳ Test manual observe trigger\n3. ⏳ Verify scheduled loop (wait 5 minutes)\n4. ⏳ Check logs for proposals created\n5. ⏳ Test proposal approval flow\n6. ⏳ Wire action coordination\n7. ⏳ Implement workflows\n\n---\n\n**Status:** READY FOR DEPLOYMENT  \n**Workers Count:** 26 (25 existing + 1 new)  \n**Breaking Changes:** None  \n**Rollback:** Available\n\n---\n\n**Last Updated:** 2026-06-09T14:45:00Z  \n**Deployment Time:** ~5 minutes  \n**Architecture:** v3.6 + Twin Orchestrator\n"}