@stackbone/cli 0.1.0-alpha.12 → 0.1.0-alpha.13

package/migrations/0017_runs_workflow_chat_triggers.sql

@@ -0,0 +1,25 @@
+-- 0017_runs_workflow_chat_triggers.sql — widen the runs/run_steps CHECKs for
+-- the eve durable runtime (feature 67).
+--
+-- The Workflow World → runs projection (F5) materialises each durable workflow
+-- as a first-class run so it shows up in the Studio timeline; it tags those rows
+-- with `trigger='workflow'` and records each workflow step as a generic
+-- `run_steps.type='workflow_step'`. The chat recorder (F6) persists every eve
+-- chat turn as a run tagged `trigger='chat'` (the chat session id rides the
+-- free-form `runs.metadata` column — no new column is added). The earlier
+-- CHECKs (0001 listed `manual/webhook/cron/event`, 0016 added `job`) predate all
+-- three values and would reject the inserts. Widen `runs_trigger_check` to match
+-- `runTriggerSchema` and `run_steps_type_check` to match the SDK `RunStepType`.
+ALTER TABLE stackbone_platform.runs DROP CONSTRAINT IF EXISTS runs_trigger_check;
+ALTER TABLE stackbone_platform.runs
+    ADD CONSTRAINT runs_trigger_check
+    CHECK (trigger IN ('manual', 'webhook', 'cron', 'event', 'job', 'workflow', 'chat'));
+
+ALTER TABLE stackbone_platform.run_steps DROP CONSTRAINT IF EXISTS run_steps_type_check;
+ALTER TABLE stackbone_platform.run_steps
+    ADD CONSTRAINT run_steps_type_check
+    CHECK (type IN (
+        'agent', 'llm_call', 'db_query', 'http_fetch',
+        'queue_publish', 'hitl_pause', 'tool_call',
+        'rag_query', 'storage_op', 'workflow_step'
+    ));

package/migrations/0018_run_steps_v2.sql

@@ -0,0 +1,167 @@
+-- 0018_run_steps_v2.sql — demolish the legacy run_steps surface and rebuild it
+-- around the eve + Workflow World step telemetry (feature 68, Fase 2 / A4).
+--
+-- The old run_steps table (0001) modelled hand-written SDK steps (`ctx.step`
+-- with types like `llm_call`/`db_query`/…), carried no token columns and was
+-- driven by the now-removed span processor / `ctx.step` writers. Feature 67 only
+-- widened its type CHECK to admit `workflow_step`; feature 68 drops the whole
+-- table and recreates it v2.
+--
+-- v2 projects the durable Workflow World step timeline (one row per World step,
+-- `type='workflow_step'`) plus, for the fast-follow, per-model-call rows
+-- (`type='model_call'`). Each row carries the four eve token counters
+-- (input/output/cache-read/cache-write); the total is derived at read time, not
+-- stored. `world_step_id` is the World correlation/idempotency key the projector
+-- upserts on. No cost column (D5 — tokens only, no $).
+--
+-- This migration also drops `runs.cost_estimated_usd` (the demolished cost
+-- accumulator) and recreates the `approvals.requested_by_step_id` FK against
+-- run_steps v2 (A6), plus the `notify_run_step_event` pg_notify trigger that the
+-- table drop took down with it.
+
+-- --------------------------------------------------------------------------
+-- Demolition (A3): drop the legacy table, the cost column and the dependent FK.
+-- --------------------------------------------------------------------------
+
+-- The FK lives on `approvals` and references the old run_steps; drop it before
+-- the table so the table drop does not have to CASCADE through it. Recreated
+-- against v2 at the end of this migration.
+ALTER TABLE stackbone_platform.approvals
+    DROP CONSTRAINT IF EXISTS approvals_requested_by_step_id_fkey;
+ALTER TABLE stackbone_platform.approvals
+    DROP COLUMN IF EXISTS requested_by_step_id;
+
+-- The AFTER INSERT/UPDATE trigger and its function are owned by the old table;
+-- drop both so the recreate below is unambiguous.
+DROP TRIGGER IF EXISTS run_steps_notify_aiu ON stackbone_platform.run_steps;
+DROP FUNCTION IF EXISTS stackbone_platform.notify_run_step_event();
+
+-- Self-referential parent FK and run FK go away with the table. CASCADE clears
+-- the dependent self-FK in one shot.
+DROP TABLE IF EXISTS stackbone_platform.run_steps CASCADE;
+
+-- The per-run cost accumulator is demolished (no $ cost anywhere in this
+-- feature).
+ALTER TABLE stackbone_platform.runs
+    DROP COLUMN IF EXISTS cost_estimated_usd;
+
+-- Per-turn token counters on `runs` (v1, A5). An eve agent CHAT turn = one
+-- `runs` row (trigger='chat'); the chat recorder stamps the four eve
+-- `data.usage` counters onto that row (the per-model-call granularity stays in
+-- run_steps, used by workflows). All nullable; the total is `input + output`,
+-- derived at read, never stored (D4). The runs timeline and feature 69's
+-- session aggregate read these directly off `runs`.
+ALTER TABLE stackbone_platform.runs
+    ADD COLUMN IF NOT EXISTS input_tokens       integer,
+    ADD COLUMN IF NOT EXISTS output_tokens      integer,
+    ADD COLUMN IF NOT EXISTS cache_read_tokens  integer,
+    ADD COLUMN IF NOT EXISTS cache_write_tokens integer;
+
+-- --------------------------------------------------------------------------
+-- Recreate run_steps v2.
+-- --------------------------------------------------------------------------
+
+CREATE TABLE stackbone_platform.run_steps (
+    id                  uuid        PRIMARY KEY DEFAULT gen_random_uuid(),
+    run_id              uuid        NOT NULL
+                                    REFERENCES stackbone_platform.runs(id) ON DELETE CASCADE,
+    -- Nullable self-FK. In practice null for flat "use step" workflows (the
+    -- World fork does not populate step-parent provenance for them), but kept
+    -- for the nested-step tree the projector derives from the event-log writer.
+    parent_step_id      uuid        REFERENCES stackbone_platform.run_steps(id) ON DELETE CASCADE,
+    type                text        NOT NULL
+                                    CHECK (type IN ('workflow_step', 'model_call')),
+    name                text,
+    status              text        NOT NULL DEFAULT 'running'
+                                    CHECK (status IN (
+                                        'pending', 'running', 'completed',
+                                        'failed', 'cancelled'
+                                    )),
+    started_at          timestamptz,
+    completed_at        timestamptz,
+    duration_ms         integer,
+    input               jsonb,
+    output              jsonb,
+    error               jsonb,
+    -- The four eve token counters (data.usage on `step.completed`). All
+    -- nullable: workflow steps carry none (the World has no tokens) and any
+    -- counter may be absent. The total is `input + output`, derived at read
+    -- time — never persisted (D4).
+    input_tokens        integer,
+    output_tokens       integer,
+    cache_read_tokens   integer,
+    cache_write_tokens  integer,
+    -- World correlation / idempotency key (= the World `stepId`). The
+    -- event-driven projector upserts on this so a replayed/retried step updates
+    -- the same row instead of inserting a duplicate.
+    world_step_id       text,
+    created_at          timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS run_steps_run_started_idx
+    ON stackbone_platform.run_steps (run_id, started_at);
+CREATE INDEX IF NOT EXISTS run_steps_parent_idx
+    ON stackbone_platform.run_steps (parent_step_id);
+
+-- Idempotent upsert target for the projector: one row per (run, World step).
+-- Partial so rows without a World correlation (e.g. future synthetic rows)
+-- never block one another on a NULL key.
+CREATE UNIQUE INDEX IF NOT EXISTS run_steps_world_step_uq
+    ON stackbone_platform.run_steps (run_id, world_step_id)
+    WHERE world_step_id IS NOT NULL;
+
+-- --------------------------------------------------------------------------
+-- Recreate the pg_notify trigger on the same `stackbone_platform_events`
+-- channel the SSE handler / emulator bus already LISTEN on. `created` fires on
+-- INSERT; `finished` fires when completed_at transitions from null to a value.
+-- --------------------------------------------------------------------------
+
+CREATE OR REPLACE FUNCTION stackbone_platform.notify_run_step_event() RETURNS trigger
+LANGUAGE plpgsql AS $fn$
+DECLARE
+    payload jsonb;
+BEGIN
+    IF TG_OP = 'INSERT' THEN
+        payload := jsonb_build_object(
+            'type', 'run.step.created',
+            'run_id', NEW.run_id,
+            'step_id', NEW.id,
+            'parent_step_id', NEW.parent_step_id,
+            'step_type', NEW.type,
+            'started_at', NEW.started_at
+        );
+    ELSIF TG_OP = 'UPDATE' THEN
+        IF (OLD.completed_at IS NULL) AND (NEW.completed_at IS NOT NULL) THEN
+            payload := jsonb_build_object(
+                'type', 'run.step.finished',
+                'run_id', NEW.run_id,
+                'step_id', NEW.id,
+                'status', NEW.status,
+                'duration_ms', NEW.duration_ms
+            );
+        ELSE
+            RETURN NULL;
+        END IF;
+    ELSE
+        RETURN NULL;
+    END IF;
+
+    PERFORM pg_notify('stackbone_platform_events', payload::text);
+    RETURN NULL;
+END;
+$fn$;
+
+DROP TRIGGER IF EXISTS run_steps_notify_aiu ON stackbone_platform.run_steps;
+CREATE TRIGGER run_steps_notify_aiu
+AFTER INSERT OR UPDATE ON stackbone_platform.run_steps
+FOR EACH ROW EXECUTE FUNCTION stackbone_platform.notify_run_step_event();
+
+-- --------------------------------------------------------------------------
+-- Recreate the approvals → run_steps FK against v2 (A6). `requestApproval`
+-- stamps the id of the workflow step that asked for the approval so the inbox
+-- can anchor it to the exact step.
+-- --------------------------------------------------------------------------
+
+ALTER TABLE stackbone_platform.approvals
+    ADD COLUMN IF NOT EXISTS requested_by_step_id uuid
+        REFERENCES stackbone_platform.run_steps(id) ON DELETE SET NULL;

package/migrations/0019_sessions.sql

@@ -0,0 +1,106 @@
+-- 0019_sessions.sql — project eve agent conversations as a first-class entity
+-- (feature 69, Fase 1).
+--
+-- An eve agent conversation is durable in the agent's Workflow World (one
+-- long-lived `workflowEntry` run per session). The control plane never read the
+-- World back, so a conversation had no row/endpoint/screen — only the loose
+-- `runs.metadata.sessionId` jsonb the chat proxy stamped on each turn. This
+-- migration adds the SESSION as a projected entity: a lean `sessions` table fed
+-- by the World→sessions projector (Fase 2), plus a real `runs.session_id` column
+-- so a session's turns join by an indexed key instead of the jsonb.
+--
+-- Lean by design (D6): `sessions` stores ONLY lifecycle (status + timestamps).
+-- The read-time aggregates (turn_count, last_activity_at, preview, tokens) are a
+-- GROUP BY over `runs` keyed on `session_id`; nothing here couples to feature
+-- 68's token columns.
+
+-- --------------------------------------------------------------------------
+-- The sessions table. `id` is the deterministic UUIDv5 the projector derives
+-- from the eve sessionId (= the `workflowEntry` World runId) under its own
+-- namespace — always caller-provided, so no gen_random_uuid default. The
+-- `status` CHECK is intentionally EXTENSIBLE (D5): v1 models only the three
+-- lifecycle states; the later HITL-in-chat feature widens it with
+-- `awaiting_input` via a non-breaking ALTER (the 0017 pattern), not a rewrite.
+-- --------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS stackbone_platform.sessions (
+    id          uuid        PRIMARY KEY,
+    -- The eve agent this conversation targets. Nullable in local (the emulator
+    -- is single-tenant), required in cloud — mirrors `runs.agent_id`.
+    agent_id    text,
+    status      text        NOT NULL DEFAULT 'open'
+                            CHECK (status IN ('open', 'completed', 'failed')),
+    started_at  timestamptz,
+    ended_at    timestamptz,
+    created_at  timestamptz NOT NULL DEFAULT now()
+);
+
+-- Cursor pagination over (created_at, id), the same keyset shape the runs list
+-- uses, so the Studio Sessions list reuses one decoder.
+CREATE INDEX IF NOT EXISTS sessions_created_at_id_idx
+    ON stackbone_platform.sessions (created_at DESC, id DESC);
+
+CREATE INDEX IF NOT EXISTS sessions_agent_status_idx
+    ON stackbone_platform.sessions (agent_id, status, created_at DESC);
+
+-- --------------------------------------------------------------------------
+-- `runs.session_id` — the real join key (D4). Stamped by the chat recorder and
+-- the projector with the SAME deterministic UUIDv5 as `sessions.id`. A LOGICAL
+-- FK only (NOT enforced): a turn can persist before the session row exists
+-- (eventual consistency; the projector and recorder race), so a real FK would
+-- reject the turn. `runs.metadata.sessionId` stays for back-compat but the join
+-- moves to this column. Indexed for the `WHERE session_id = :id` turn lookup.
+-- --------------------------------------------------------------------------
+ALTER TABLE stackbone_platform.runs
+    ADD COLUMN IF NOT EXISTS session_id uuid;
+
+CREATE INDEX IF NOT EXISTS runs_session_id_idx
+    ON stackbone_platform.runs (session_id, created_at)
+    WHERE session_id IS NOT NULL;
+
+-- --------------------------------------------------------------------------
+-- pg_notify trigger on the SAME `stackbone_platform_events` channel the
+-- runs/run_steps/approvals triggers use, so the cloud `StudioStreamService` (one
+-- LISTEN) and the emulator's run-steps-bridge forward `session.*` with no new
+-- infra. `created` fires on INSERT; `updated` fires when the lifecycle actually
+-- moved (status or ended_at changed) so an idempotent re-upsert of the same
+-- state does not spam the stream.
+-- --------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION stackbone_platform.notify_session_event() RETURNS trigger
+LANGUAGE plpgsql AS $fn$
+DECLARE
+    payload jsonb;
+BEGIN
+    IF TG_OP = 'INSERT' THEN
+        payload := jsonb_build_object(
+            'type', 'session.created',
+            'session_id', NEW.id,
+            'agent_id', NEW.agent_id,
+            'status', NEW.status,
+            'started_at', NEW.started_at,
+            'created_at', NEW.created_at
+        );
+    ELSIF TG_OP = 'UPDATE' THEN
+        IF (OLD.status IS DISTINCT FROM NEW.status)
+           OR (OLD.ended_at IS DISTINCT FROM NEW.ended_at) THEN
+            payload := jsonb_build_object(
+                'type', 'session.updated',
+                'session_id', NEW.id,
+                'status', NEW.status,
+                'ended_at', NEW.ended_at
+            );
+        ELSE
+            RETURN NULL;
+        END IF;
+    ELSE
+        RETURN NULL;
+    END IF;
+
+    PERFORM pg_notify('stackbone_platform_events', payload::text);
+    RETURN NULL;
+END;
+$fn$;
+
+DROP TRIGGER IF EXISTS sessions_notify_aiu ON stackbone_platform.sessions;
+CREATE TRIGGER sessions_notify_aiu
+AFTER INSERT OR UPDATE ON stackbone_platform.sessions
+FOR EACH ROW EXECUTE FUNCTION stackbone_platform.notify_session_event();

package/migrations/0020_runs_entity_name.sql

@@ -0,0 +1,23 @@
+-- 0020_runs_entity_name.sql — record which agent/workflow a run belongs to.
+--
+-- The Studio Runs screen lists a run's id, trigger and status but never the
+-- NAME of the agent or workflow that produced it, so a workspace running several
+-- eve agents + workflows could not tell whose run a row was, nor filter by it.
+-- The name is known at run-creation time (the chat proxy has the agent `:name`;
+-- the workflow start has the workflow `:name`) but was dropped.
+--
+-- `entity_name` denormalises that name onto the run so the list renders it as a
+-- column and filters by it without a join. It is the agent name for `chat` runs
+-- and the workflow name for `workflow` runs; combined with the existing
+-- `trigger` the UI knows the kind. Nullable: classic/manual cloud runs (eve is
+-- dev-only) leave it NULL. Distinct from `agent_id`, which in cloud is the agent
+-- TEMPLATE id (a stable identifier, not a display name) and is null for workflows.
+
+ALTER TABLE stackbone_platform.runs
+    ADD COLUMN IF NOT EXISTS entity_name text;
+
+-- Backs both the exact-match filter (`WHERE entity_name = $1`) and the distinct
+-- list that populates the Runs screen's name dropdown.
+CREATE INDEX IF NOT EXISTS runs_entity_name_idx
+    ON stackbone_platform.runs (entity_name)
+    WHERE entity_name IS NOT NULL;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackbone/cli",
-  "version": "0.1.0-alpha.12",
+  "version": "0.1.0-alpha.13",
   "license": "UNLICENSED",
   "type": "module",
   "bin": {
@@ -34,7 +34,7 @@
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
     "postgres": "^3.4.9",
-    "unpdf": "^0.12.1",
+    "tar": "^7.5.13",
     "yaml": "^2.8.3",
     "zod": "^4.3.6"
   }