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.