Dependencies

Overview

Sessions within a project can declare dependencies on other sessions in the same project. Dependencies enable multi-stage investigation workflows where downstream sessions build on the findings of upstream sessions.

There are two types of dependencies:

• Unconditional — The downstream session waits until the upstream session has completed (produced at least one key result).
• Conditional — The downstream session waits until the upstream session's disposition contains a specific value for an enumerated field.

When a session has dependencies, the system checks whether they are satisfied before allowing the session to start. If all dependencies are satisfied, the upstream sessions' key results and dispositions are automatically injected into the AI's prompt, giving the downstream session full context about what was learned upstream.

Unconditional Dependencies

An unconditional dependency means "wait until this session is done." A session is considered complete when it produces its first key result via the PROMOTE_RESULT tool, or when it has set a disposition, at which point its status is set to "COMPLETE".

Use unconditional dependencies when the downstream session just needs the upstream session to have finished its investigation, regardless of what it found.

Conditional Dependencies

A conditional dependency means "wait until this session's disposition has a specific value for an enumerated field." For example, a downstream session might depend on an upstream session having risk_level = HIGH.

Conditional dependencies require that:

• The upstream session has a disposition schema with at least one enumerated list field (pipe-separated values like HIGH|MEDIUM|LOW).
• The condition specifies exactly one key-value pair from the schema's enum fields.

Use conditional dependencies to create branching workflows — for example, only running a deep-dive investigation when an initial triage session classifies risk as HIGH.

Adding Dependencies

Dependencies can be added in two places:

1. When creating a new session — If the project has other sessions, a "Dependencies" editor appears on the new session form between the disposition schema editor and the starting request textarea.

2. When editing an existing session — From the project detail page, click the pencil icon on a session to open the edit panel, which includes the dependency editor (when the project has more than one session).

Dependency Satisfaction

Dependencies are checked in two contexts:

1. At session start — When a user attempts to start a session with dependencies, the backend verifies that all dependencies are satisfied. If any dependency is not satisfied, the session cannot start and an error message is displayed.

2. On the project detail page — The frontend uses the same resolution logic to display dependency status on each session card. Dependency tags appear below the session name showing which sessions it depends on.

Once a downstream session has started (has a conversation log), dependencies are not re-validated. This means that if an upstream session's disposition changes after the downstream session has already started, the downstream session is not affected.

Blocked Sessions

When you navigate to a session that has unsatisfied dependencies, the session workspace shows a blocked state instead of the starting request form. The blocked state displays:

• A "Dependencies Not Satisfied" heading.
• A list of specific issues explaining why each dependency is not met:
  • "Session Name" has not completed yet — for unconditional dependencies where the upstream session hasn't promoted a key result.
  • "Session Name" disposition key is not "value" — for conditional dependencies where the upstream session's disposition doesn't match.
  • Upstream session has been deleted — when a depended-on session has been deleted.
  • Schema key "key" no longer exists on "Session Name" — when the upstream session's disposition schema has been edited and no longer contains the expected field.

Revisit the session after the upstream sessions have completed or been resolved.

Upstream Context Injection

When a session with satisfied dependencies starts, the system automatically queries the upstream sessions' key results from the database and injects them into the AI's prompt. The injected context appears between the project system prompt and the keyword instructions and includes, for each upstream session:

• The upstream session's name.
• The upstream session's disposition (if set).
• Each key result: title, description, SQL query, and data (truncated to 20 rows for large result sets).

This gives the downstream AI full context about what was learned in upstream sessions without requiring the user to manually summarize or copy information.

Warnings and Deleted Sessions

The project detail page displays warnings for structural dependency issues:

• Deleted upstream session — If an upstream session that other sessions depend on is deleted, a yellow warning appears on the dependent sessions.
• Schema changed — If an upstream session's disposition schema is edited to remove a field that a conditional dependency references, a warning appears on the dependent sessions.

These warnings indicate that the dependency configuration may need to be updated. The dependent session will be blocked from starting until the issue is resolved (by editing the dependency or restoring/recreating the upstream session).

When deleting a session that other sessions depend on, the confirmation dialog warns you about the dependent sessions and shows how many would be affected.

Example Workflow

Scenario: A team is investigating pharmacy cost anomalies. They want an initial triage session to classify risk, and then a deep-dive session that only runs for high-risk anomalies.

1. Create a project called "Pharmacy Cost Review" with appropriate system prompt and tools.

2. Create Session A ("Triage") with a disposition schema:

   • risk_level: Custom List — LOW|MEDIUM|HIGH
   • category: String

3. Start Session A. The AI investigates the data, finds a significant anomaly, and promotes key results showing the evidence. It then proposes a disposition of risk_level: HIGH, category: "Brand vs Generic". You agree, and the AI sets the disposition.

4. Create Session B ("Deep Dive") with:

   • A conditional dependency on Session A: risk_level = HIGH
   • A starting request like "Investigate the brand vs generic cost drivers identified in the triage session."

5. Because Session A's disposition has risk_level = HIGH, the dependency is satisfied. Session B can start immediately. The AI receives the full context from Session A — the triage disposition, all key results with their SQL and data — and builds on those findings.

6. Create Session C ("Low Risk Review") with:

   • A conditional dependency on Session A: risk_level = LOW

7. Session C shows a blocked state because Session A's disposition has risk_level = HIGH, not LOW. If the team later re-runs the triage and the new triage session has risk_level = LOW, Session C's dependency can be updated to point to the new session.