elsa-core/specs/008-weaver-ai-copilot/spec.md

# Feature Specification: Weaver AI Copilot Platform

**Feature Branch**: `codex/008-weaver-ai-copilot`  
**Created**: 2026-05-20  
**Status**: Draft  
**Input**: User description: "Implement Weaver, an AI assistant / agent that provides agentic workflow authoring and management similar to GitHub Copilot, integrated as a chat interface in Elsa Studio."

## Clarifications

### Session 2026-05-20

- Q: What durability level should Weaver require for MVP conversations, proposals, and audit records? → A: Durable proposals and audit required; conversation history retention configurable.
- Q: Should Weaver require separation of duties between the user who requests an AI proposal and the user who approves/applies it? → A: Same authorized user may request, approve, and apply proposals.
- Q: When third-party modules or MCP servers contribute Weaver tools, should those tools become available automatically? → A: Auto-enable read-only module tools; require explicit enablement for proposal, administrative, and MCP tools.

### Session 2026-05-21

- Q: What should Weaver do when chat stream clients disconnect during an in-progress turn? → A: Continue the turn for a short grace window, persist durable outputs, and allow reconnect.
- Q: For runtime trend analysis, what data scope may Weaver inspect by default? → A: Attached references plus user-selected time range and diagnostics scope.

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Chat with workflow-aware Weaver (Priority: P1)

An Elsa Studio user opens a Weaver panel, attaches workflow or runtime references, asks a question, and receives a streaming answer with visible tool progress and results.

**Why this priority**: Conversational access is the foundation for every authoring, diagnostics, and operations use case.

**Independent Test**: Start a chat with a workflow definition reference, verify the server resolves context, streams message deltas, emits tool progress, and completes the conversation without Studio contacting an AI provider directly.

**Acceptance Scenarios**:

1. **Given** a user with permission to view a workflow definition, **When** they ask Weaver to explain that workflow, **Then** Weaver streams an answer grounded in server-resolved workflow context.
2. **Given** a chat request with context attachment references, **When** the server receives the request, **Then** the server resolves only the authorized data needed for the turn and redacts sensitive values before model context is built.
3. **Given** a tool is invoked during a chat turn, **When** the tool starts, progresses, returns, or fails, **Then** Studio receives stream events that can render the tool lifecycle.

---

### User Story 2 - Generate workflows through reviewable proposals (Priority: P2)

A workflow author describes a desired workflow in natural language and receives a structured workflow proposal with rationale, validation diagnostics, warnings, and graph diff before any workflow is persisted.

**Why this priority**: Safe creation is the first high-value authoring workflow and proves the proposal-only mutation model.

**Independent Test**: Ask Weaver to create a workflow, inspect the proposal, validate it, approve it, and verify the workflow is applied only after approval and audit entries are recorded.

**Acceptance Scenarios**:

1. **Given** a user can create workflows, **When** they ask Weaver to generate one, **Then** Weaver creates a proposal with workflow payload, rationale, warnings, validation diagnostics, graph preview, and proposal ID.
2. **Given** a generated proposal has validation errors, **When** the user attempts to apply it, **Then** the server blocks application and returns the validation diagnostics.
3. **Given** a valid proposal is approved, **When** the user applies it, **Then** the server persists the workflow and records the approval, actor, tenant, and applied change.

---

### User Story 3 - Edit and validate existing workflows safely (Priority: P3)

A workflow author asks Weaver to modify, explain, or validate an existing workflow and receives proposed changes with an understandable graph diff and risk summary.

**Why this priority**: Editing existing workflows is more common and riskier than greenfield creation, so it builds on the proven proposal lifecycle.

**Independent Test**: Attach an existing workflow, ask Weaver for a targeted change, verify the returned diff is reviewable, validation runs before apply, and direct AI persistence is impossible.

**Acceptance Scenarios**:

1. **Given** a user can edit a workflow, **When** they ask Weaver to add or change workflow behavior, **Then** Weaver returns a proposal rather than directly saving changes.
2. **Given** a proposed edit may break existing behavior, **When** validation runs, **Then** the proposal includes warnings and blocking diagnostics that Studio can display.
3. **Given** a user asks why a workflow behaves a certain way, **When** Weaver analyzes the definition, **Then** the answer explains structure, activities, inputs, outputs, and likely execution path without creating a proposal.

---

### User Story 4 - Analyze runtime incidents conversationally (Priority: P4)

An operator attaches workflow instance, diagnostics, log, or time-range references and asks Weaver to summarize failures, identify failing activities, inspect state, and highlight recurring trends.

**Why this priority**: Runtime intelligence reduces operational friction and turns existing Elsa telemetry into actionable guidance.

**Independent Test**: Provide failed instance and log references, ask for an incident summary, and verify Weaver uses read-only tools to produce a grounded summary with failing activities, evidence, and next investigation steps.

**Acceptance Scenarios**:

1. **Given** a user can inspect a workflow instance, **When** they ask Weaver why it failed, **Then** Weaver summarizes errors, activity state, relevant history, and probable causes using authorized runtime data.
2. **Given** attached runtime references plus a user-selected time range and diagnostics scope with multiple failures, **When** the user asks for trends, **Then** Weaver identifies recurring workflows, activities, error categories, and time patterns within that selected scope.
3. **Given** runtime data includes secrets or sensitive configuration, **When** Weaver builds context or returns results, **Then** sensitive values are redacted.

---

### User Story 5 - Extend Weaver with governed tools and agents (Priority: P5)

A module author contributes tools, context providers, custom agents, or external tool integrations that are scoped by permissions, tenant behavior, danger level, mutability, and audit policy.

**Why this priority**: Weaver must become a platform capability rather than a closed feature owned only by the core AI module.

**Independent Test**: Register a module-provided read-only tool and a proposal tool, verify they appear in capabilities, execute only when authorized, and emit audit and telemetry records.

**Acceptance Scenarios**:

1. **Given** a module registers an AI tool, **When** Weaver capabilities are requested, **Then** the tool is listed with schema, permissions, mutability, danger level, tenant behavior, and audit behavior.
2. **Given** a tool requires permissions the current user lacks, **When** an agent attempts to invoke it, **Then** the server denies execution and records the denial.
3. **Given** a custom agent is registered with a scoped tool set, **When** Weaver delegates to that agent, **Then** the agent can only access its allowed tools and context providers.
4. **Given** a module registers proposal, administrative, or MCP-backed tools, **When** the module is enabled, **Then** those tools remain unavailable until explicitly enabled by an authorized administrator.

### Edge Cases

- Chat requests reference deleted, inaccessible, or cross-tenant workflow data.
- Streaming clients that disconnect mid-turn can reconnect during a configurable grace window and recover durable outputs produced while disconnected.
- Tool execution exceeds limits, fails validation, or returns more data than can be safely included in model context.
- Proposal payloads become stale because the workflow changed after the proposal was created.
- Same-actor proposal approval and application still require explicit user action and audit records.
- A third-party tool declares unsafe metadata or attempts to bypass server authorization.
- Provider runtime is unavailable, misconfigured, or incompatible with the configured adapter version.
- Users ask Weaver to reveal secrets, credentials, or sensitive configuration.

## Requirements *(mandatory)*

### Functional Requirements

- **FR-001**: System MUST provide a Weaver chat experience in Elsa Studio that communicates only with Elsa Server APIs.
- **FR-002**: Studio MUST send context references, not raw workflow, runtime, diagnostic, tenant, or activity data.
- **FR-003**: Server MUST resolve context attachments according to tenant scope, ownership, and user permissions.
- **FR-004**: System MUST stream assistant message deltas, tool progress, tool results, proposal notifications, errors, and completion events.
- **FR-005**: System MUST support configurable conversation and session history retention; conversation durability is configurable for MVP.
- **FR-006**: System MUST expose capabilities and tool metadata so Studio can render available Weaver behavior.
- **FR-007**: AI-originated workflow creation and edit output MUST be represented as proposals, never direct persisted workflow mutations.
- **FR-008**: Workflow proposals MUST include structured workflow payload, rationale, warnings, validation diagnostics, graph diff or preview, and proposal ID.
- **FR-009**: Server MUST validate proposals before they can be applied.
- **FR-010**: The same authorized user MUST be able to request, approve, reject, and apply proposals in MVP.
- **FR-011**: System MUST block proposal application when validation fails or when the source workflow revision no longer matches the proposal baseline.
- **FR-012**: System MUST durably audit prompts, model/session events, tool calls, proposal diffs, approvals, rejections, applied changes, timestamps, actors, and tenant IDs.
- **FR-013**: System MUST provide built-in read-only workflow tools for getting definitions, listing definitions, getting instances, searching instances, and reading the activity catalog.
- **FR-014**: System MUST provide built-in proposal tools for proposing workflow creation, proposing workflow updates, and validating draft workflow payloads.
- **FR-015**: Runtime diagnostics tools MUST support failure inspection, incident summaries, failing activity identification, execution history review, and trend analysis.
- **FR-016**: Tools MUST execute server-side and use published Elsa abstractions rather than bypassing authorization or direct persistence boundaries.
- **FR-017**: Third-party modules MUST be able to register AI tools, context providers, custom agents, and external tool integrations.
- **FR-018**: Every registered tool MUST declare schema, danger level, mutability, permissions, tenant behavior, and audit behavior.
- **FR-019**: System MUST support local and remote external tool servers with allowlists, per-agent scoping, and explicit administrator enablement.
- **FR-020**: System MUST keep AI provider/runtime details isolated from Studio contracts, workflow models, and Elsa core abstractions.
- **FR-021**: System MUST support provider-agnostic configuration with a bring-your-own-key model where applicable.
- **FR-022**: System MUST support telemetry for trace correlation, tool execution metrics, model/session events, and proposal lifecycle metrics.
- **FR-023**: System MUST redact secrets and sensitive configuration before data enters model context, tool results, streamed events, audit records, or proposal rationale.
- **FR-024**: Administrative mutation tools such as tenant modification, workflow deletion, or instance termination MUST remain out of MVP scope.
- **FR-025**: Read-only tools registered by enabled modules MAY be available by default, but proposal, administrative, and MCP-backed tools MUST require explicit administrator enablement before use.
- **FR-026**: System MUST continue in-progress chat turns for a configurable disconnect grace window, persist durable outputs produced during that window, and allow authorized clients to reconnect to recover them.
- **FR-027**: Runtime trend analysis MUST be limited by default to attached references plus an explicit user-selected time range and diagnostics scope.

### Key Entities *(include if feature involves data)*

- **AI Conversation**: A user-visible Weaver chat thread with messages, participants, tenant, timestamps, context attachment references, provider session reference, and configurable retention behavior.
- **AI Session**: Server-managed runtime session used to execute agent turns, stream events, invoke tools, and resume conversations.
- **Context Attachment**: A reference to workflow, runtime, activity, tenant, diagnostic, or time-range context that the server resolves safely.
- **AI Tool Definition**: Registered capability with schema, permissions, mutability, danger level, tenant behavior, audit behavior, and agent scope.
- **Tool Invocation**: A single attempted tool execution with arguments, authorization result, progress, output summary, telemetry, and audit metadata.
- **Workflow Proposal**: A durable reviewable AI-generated workflow creation or edit package with baseline, payload, rationale, warnings, diagnostics, graph diff, state, and apply result.
- **AI Audit Event**: Durable record of prompt, context resolution, tool invocation, proposal lifecycle, approval, application, or denial.
- **AI Agent Definition**: Named behavior profile with prompt, allowed tools, allowed context providers, external integrations, and governance metadata.
- **External Tool Server Registration**: Governed local or remote integration endpoint with allowlist, agent scoping, and audit policy.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: An authorized user can start a Weaver chat with workflow context and receive first streamed output within 3 seconds under normal server load.
- **SC-002**: At least 95% of valid workflow generation requests in MVP produce a reviewable proposal with payload, rationale, diagnostics, and graph preview without directly persisting changes.
- **SC-003**: Proposal application is blocked 100% of the time when validation fails, authorization fails, or the workflow baseline is stale.
- **SC-004**: Runtime incident analysis can identify the failed workflow instance, failing activity, primary error, and relevant execution evidence for seeded test incidents.
- **SC-005**: Third-party modules can register at least one read-only tool and one proposal tool without changing core Weaver orchestration code.
- **SC-006**: Studio never sends raw workflow/runtime datasets or provider credentials to an AI provider directly.
- **SC-007**: All tool executions and proposal lifecycle transitions create audit records with actor and tenant metadata.
- **SC-008**: Provider-specific runtime types are absent from Elsa core abstractions, Studio contracts, and workflow definition models.

## Assumptions

- Weaver is the product name for the Elsa Studio AI assistant and server-hosted AI platform surface.
- The first implementation targets Elsa Server plus a paired Elsa Studio module; code changes in the Studio repository will be tracked separately if that repository is not present in this workspace.
- Existing Elsa identity, tenancy, workflow definition, workflow instance, activity catalog, diagnostics, logging, and validation services remain the source of truth.
- MVP supports workflow authoring proposals and read-only runtime diagnostics; administrative destructive actions are deferred.
- Conversation history retention is configurable for MVP, while workflow proposals and audit records require durable persistence.
- Provider runtime integration is isolated behind a module boundary so preview or unstable provider APIs can change without breaking Elsa contracts.