@nauticana/sail 1.1.19 → 1.1.20

package/src/agent/component/turn_event_list.ts

@@ -0,0 +1,23 @@
+import { ChangeDetectionStrategy, Component, TemplateRef, computed, input } from '@angular/core';
+import { JsonPipe, NgTemplateOutlet } from '@angular/common';
+import { MatIconModule } from '@angular/material/icon';
+import { TurnEvent, TurnExtensionEvent } from '../model/turn_event';
+import { buildTurnTimeline } from '../util/turn_timeline';
+
+/**
+ * Renders one turn's typed events in frame order. Extension events render only through
+ * `extensionTemplate`; without it, and for types it does not handle, they are ignored.
+ * Ships no CSS — style the `.turn-*` hooks. Selector: <sail-turn-event-list>.
+ */
+@Component({
+  selector: 'sail-turn-event-list',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [JsonPipe, NgTemplateOutlet, MatIconModule],
+  templateUrl: './turn_event_list.html',
+})
+export class TurnEventListComponent {
+  readonly events = input.required<readonly TurnEvent[]>();
+  readonly extensionTemplate = input<TemplateRef<{ $implicit: TurnExtensionEvent }>>();
+
+  protected readonly items = computed(() => buildTurnTimeline(this.events()));
+}

package/src/agent/component/turn_stream_view.html

@@ -0,0 +1,36 @@
+<div class="turn-stream" [attr.data-status]="status()">
+  <sail-turn-event-list [events]="events()" [extensionTemplate]="extensionTemplate()" />
+
+  @if (storedPayload() !== undefined) {
+    @if (isText(storedPayload())) {
+      <p class="turn-stream__stored">{{ storedPayload() }}</p>
+    } @else {
+      <pre class="turn-stream__stored">{{ storedPayload() | json }}</pre>
+    }
+  }
+
+  @switch (status()) {
+    @case ('streaming') {
+      <mat-progress-bar mode="indeterminate" aria-label="Agent is responding" />
+    }
+    @case ('awaiting_approval') {
+      <p class="turn-stream__status" role="status">Waiting for approval. The conversation continues once it is decided.</p>
+    }
+    @case ('cancelling') {
+      <p class="turn-stream__status" role="status">Cancelling…</p>
+    }
+    @case ('canceled') {
+      <p class="turn-stream__status" role="status">Canceled</p>
+    }
+    @case ('failed') {
+      <p class="turn-stream__status turn-stream__status--failed" role="alert">Turn failed: {{ finalFrame()?.error_code }}</p>
+    }
+    @case ('replay_expired') {
+      <p class="turn-stream__status" role="status">Loading the stored result…</p>
+    }
+  }
+
+  @if (canCancel()) {
+    <button matButton type="button" (click)="requestCancel()">Cancel</button>
+  }
+</div>

package/src/agent/component/turn_stream_view.ts

@@ -0,0 +1,46 @@
+import { ChangeDetectionStrategy, Component, TemplateRef, computed, input, output } from '@angular/core';
+import { JsonPipe } from '@angular/common';
+import { MatButtonModule } from '@angular/material/button';
+import { MatProgressBarModule } from '@angular/material/progress-bar';
+import { TurnExtensionEvent } from '../model/turn_event';
+import { TurnStream } from '../service/turn_stream';
+import { TurnEventListComponent } from './turn_event_list';
+
+/**
+ * One turn's stream: its events, its status, and a cancel request. The app owns the transport
+ * and the cancel call; on `cancelRequested` it sends the request and calls
+ * `stream.markCancelRequested()`. Selector: <sail-turn-stream-view>.
+ */
+@Component({
+  selector: 'sail-turn-stream-view',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [JsonPipe, MatButtonModule, MatProgressBarModule, TurnEventListComponent],
+  templateUrl: './turn_stream_view.html',
+})
+export class TurnStreamViewComponent {
+  readonly stream = input.required<TurnStream>();
+  readonly extensionTemplate = input<TemplateRef<{ $implicit: TurnExtensionEvent }>>();
+
+  readonly cancelRequested = output<string>();
+
+  protected readonly status = computed(() => this.stream().status());
+  protected readonly events = computed(() => this.stream().events());
+  protected readonly finalFrame = computed(() => this.stream().finalFrame());
+  protected readonly canCancel = computed(() => {
+    const status = this.status();
+    return status === 'streaming' || status === 'awaiting_approval';
+  });
+  /** A synthesized final frame carries the whole answer in its payload and no events. */
+  protected readonly storedPayload = computed(() => {
+    const frame = this.finalFrame();
+    return frame && !frame.error_code && this.events().length === 0 ? frame.payload : undefined;
+  });
+
+  protected isText(payload: unknown): payload is string {
+    return typeof payload === 'string';
+  }
+
+  protected requestCancel(): void {
+    this.cancelRequested.emit(this.stream().requestId);
+  }
+}

package/src/agent/index.ts

@@ -0,0 +1,14 @@
+export * from './model/agent_studio';
+export * from './model/turn_event';
+export * from './model/reply_frame';
+export * from './model/decision';
+export * from './service/agent_studio.service';
+export * from './service/turn_stream';
+export * from './util/studio_errors';
+export * from './util/turn_timeline';
+export * from './component/prompt_section_editor';
+export * from './component/prompt_language_editor';
+export * from './component/release_sections';
+export * from './component/turn_event_list';
+export * from './component/turn_stream_view';
+export * from './component/decision_timeline';

package/src/agent/model/agent_studio.ts

@@ -0,0 +1,198 @@
+/** Agent Studio `studio-v2` wire types. Field names are the backend's JSON names. */
+
+export type AgentMergeMode = 'append' | 'replace';
+export type AgentResetScope = 'agent_override' | 'type_default' | 'platform_baseline';
+
+export interface AgentSummary {
+  agent_type: string;
+  agent_name: string;
+  display_name: string;
+  purpose: string;
+  enabled: boolean;
+  is_default: boolean;
+  readiness: string;
+  readiness_reason: string;
+  type_defaults_revision: number;
+  agent_revision: number;
+  published_version: number;
+  published_at?: string;
+  last_run_at?: string;
+}
+
+export interface AgentFieldError {
+  field: string;
+  message: string;
+}
+
+export interface AgentValidationProblem {
+  message: string;
+  fields: AgentFieldError[];
+}
+
+export interface AgentModelSelection {
+  text_model: string;
+  image_model: string;
+  video_model: string;
+}
+
+export interface AgentApprovalPolicy {
+  require_approval: boolean;
+}
+
+/** One contribution to a prompt section. `editable` is response-only. */
+export interface AgentPromptLayer {
+  scope_id: string;
+  scope_kind: string;
+  merge_mode: AgentMergeMode;
+  sealed: boolean;
+  editable: boolean;
+  instruction: string;
+  output: string;
+}
+
+export interface AgentPromptSection {
+  prompt_header_id: number;
+  caption: string;
+  description: string;
+  /** Widest scope first; the order is the server's and is never re-sorted. */
+  layers: AgentPromptLayer[];
+  effective_text: string;
+  effective_output: string;
+}
+
+export interface AgentLanguageDraft {
+  language_code: string;
+  prompt_sections: AgentPromptSection[];
+}
+
+export interface AgentDrift {
+  active_version: number;
+  changed_languages: string[];
+  causes: string[];
+}
+
+export interface AgentDraft {
+  agent_type: string;
+  agent_name: string;
+  display_name: string;
+  enabled: boolean;
+  is_default: boolean;
+  approval_policy: AgentApprovalPolicy;
+  models: AgentModelSelection;
+  languages: AgentLanguageDraft[];
+  agent_scope_id?: string;
+  type_scope_id?: string;
+  drift?: AgentDrift;
+  expected_type_defaults_revision: number;
+  expected_agent_revision: number;
+}
+
+export interface AgentTestRequest {
+  agent_name: string;
+  language_code: string;
+  task: string;
+  input_data: string;
+}
+
+export interface AgentTestResult {
+  agent_name: string;
+  language_code: string;
+  model: string;
+  digest: string;
+  output: string;
+  latency_ms: number;
+  input_tokens: number;
+  output_tokens: number;
+  credits: number;
+  sections: string[];
+}
+
+export interface AgentPublishRequest {
+  agent_name: string;
+  change_summary: string;
+  expected_agent_revision: number;
+  expected_type_defaults_revision: number;
+}
+
+export interface AgentRestoreRequest {
+  agent_name: string;
+  version: number;
+}
+
+/** `prompt_header_id` 0 and `language_code` '' leave that dimension unnarrowed. */
+export interface AgentResetRequest {
+  agent_name: string;
+  scope: AgentResetScope;
+  prompt_header_id: number;
+  language_code: string;
+  expected_agent_revision: number;
+  expected_type_defaults_revision: number;
+}
+
+export interface AgentSetDefaultRequest {
+  agent_name: string;
+  expected_type_defaults_revision: number;
+}
+
+export interface AgentSetEnabledRequest {
+  agent_name: string;
+  enabled: boolean;
+  expected_agent_revision: number;
+}
+
+export interface AgentEnabledState {
+  enabled: boolean;
+  expected_agent_revision: number;
+}
+
+export interface AgentRelease {
+  agent_name: string;
+  agent_type: string;
+  version: number;
+  enabled: boolean;
+  models: AgentModelSelection;
+  require_approval: boolean;
+  definition_digest: string;
+  change_summary: string;
+  published_by: number;
+  published_at: string;
+  active: boolean;
+  languages: string[];
+}
+
+export interface AgentAuditEvent {
+  event: string;
+  detail: string;
+  user_id: number;
+  event_time: string;
+}
+
+/** The layer that decided a section when its release was compiled. */
+export interface AgentPromptSource {
+  scope_id: string;
+  scope_kind: string;
+  merge_mode: AgentMergeMode;
+  sealed: boolean;
+}
+
+export interface AgentReleaseSection {
+  language_code: string;
+  prompt_header_id: number;
+  caption: string;
+  description: string;
+  instruction: string;
+  output: string;
+  sequence: number;
+  source: AgentPromptSource;
+}
+
+export interface StudioModel {
+  id: string;
+  provider: string;
+  model_type: string;
+  display_name: string;
+  input_credits_per_1k: number;
+  output_credits_per_1k: number;
+  image_credits: number;
+  video_credits_per_sec: number;
+}

package/src/agent/model/decision.ts

@@ -0,0 +1,43 @@
+import { ObjectRef } from './turn_event';
+
+export type DecisionOutcome = 'allow' | 'deny' | 'pending';
+
+export interface PrincipalRef {
+  kind: string;
+  id: string;
+}
+
+export interface AuthorityRef {
+  subject: PrincipalRef;
+  grant_id?: string;
+  grantor?: PrincipalRef;
+}
+
+/**
+ * One audit record as sail renders it. The audit endpoint is the app's, so the app maps its
+ * response onto this shape; `id` is whatever key the endpoint gives a record.
+ */
+export interface DecisionRecord {
+  id: string | number;
+  category: string;
+  action: string;
+  resource: string;
+  outcome: DecisionOutcome;
+  reason: string;
+  principal: PrincipalRef;
+  authority?: AuthorityRef;
+  scope_id?: string;
+  release_version?: string;
+  policy_id?: string;
+  policy_version?: string;
+  obligations?: string[];
+  evidence?: ObjectRef;
+  request_id: string;
+  conversation_id?: string;
+  occurred_at: string;
+}
+
+export interface DecisionCategoryGroup {
+  category: string;
+  records: DecisionRecord[];
+}

package/src/agent/model/reply_frame.ts

@@ -0,0 +1,30 @@
+import { TurnEvent } from './turn_event';
+
+export const TURN_ERROR_CANCELED = 'canceled';
+
+/**
+ * One reply frame as sail consumes it. The backend's reply type fixes no JSON names, so the
+ * app's transport adapter maps its own wire shape onto this one.
+ */
+export interface TurnReplyFrame {
+  request_id: string;
+  conversation_id: string;
+  sequence: number;
+  events: TurnEvent[];
+  final: boolean;
+  error_code?: string;
+  /** Opaque product payload; on a synthesized final frame it is the whole answer. */
+  payload?: unknown;
+  agent_version?: string;
+  emitted_at?: string;
+}
+
+export type TurnStreamStatus =
+  | 'idle'
+  | 'streaming'
+  | 'awaiting_approval'
+  | 'cancelling'
+  | 'completed'
+  | 'canceled'
+  | 'failed'
+  | 'replay_expired';

package/src/agent/model/turn_event.ts

@@ -0,0 +1,95 @@
+/** Typed turn events (`v` 1). Exactly the member a `kind` names is set. */
+
+export const TURN_EVENT_KINDS = [
+  'text_delta',
+  'tool_proposal',
+  'tool_result',
+  'approval_pending',
+  'approval_resolved',
+  'evidence',
+  'effect',
+  'progress',
+  'result',
+  'extension',
+] as const;
+
+export type TurnEventKind = (typeof TURN_EVENT_KINDS)[number];
+export type EffectStatus = 'satisfied' | 'violated' | 'unknown';
+
+/** A reference to stored content, never the content itself. */
+export interface ObjectRef {
+  URI: string;
+  Digest: string;
+}
+
+export interface TurnToolEvent {
+  call_id: string;
+  tool_id: string;
+  tool_version: string;
+  arguments?: unknown;
+  output?: unknown;
+  is_error?: boolean;
+}
+
+export interface EffectObservation {
+  status: EffectStatus;
+  reason?: string;
+  observed_at?: string;
+  evidence?: ObjectRef[];
+  /** The effect already held, so the mutation was not sent again. */
+  reconciled?: boolean;
+}
+
+export interface TurnEffectEvent {
+  call_id: string;
+  tool_id: string;
+  tool_version: string;
+  observation: EffectObservation;
+}
+
+export interface TurnApprovalEvent {
+  call_id?: string;
+  tool_id?: string;
+  decision?: string;
+}
+
+export interface EvidenceRef {
+  id: string;
+  source: string;
+  object?: ObjectRef;
+  call_id?: string;
+  uri?: string;
+}
+
+export interface TurnProgressEvent {
+  stage: string;
+  iteration?: number;
+  message?: string;
+}
+
+export interface TurnExtensionEvent {
+  type: string;
+  v: number;
+  payload?: unknown;
+}
+
+export interface TurnEvent {
+  v: number;
+  kind: TurnEventKind;
+  text?: string;
+  tool?: TurnToolEvent;
+  approval?: TurnApprovalEvent;
+  evidence?: EvidenceRef[];
+  effect?: TurnEffectEvent;
+  progress?: TurnProgressEvent;
+  extension?: TurnExtensionEvent;
+}
+
+const knownKinds: ReadonlySet<string> = new Set(TURN_EVENT_KINDS);
+
+/** Narrows a received frame member; unknown kinds are dropped by callers, not reported. */
+export function isKnownTurnEvent(value: unknown): value is TurnEvent {
+  if (!value || typeof value !== 'object') return false;
+  const kind = (value as { kind?: unknown }).kind;
+  return typeof kind === 'string' && knownKinds.has(kind);
+}

package/src/agent/service/agent_studio.service.ts

@@ -0,0 +1,85 @@
+import { Injectable } from '@angular/core';
+import { Observable } from 'rxjs';
+import { BaseRestService } from '../../service/base_rest.service';
+import {
+  AgentAuditEvent,
+  AgentDraft,
+  AgentEnabledState,
+  AgentPublishRequest,
+  AgentRelease,
+  AgentReleaseSection,
+  AgentResetRequest,
+  AgentRestoreRequest,
+  AgentSetDefaultRequest,
+  AgentSetEnabledRequest,
+  AgentSummary,
+  AgentTestRequest,
+  AgentTestResult,
+  StudioModel,
+} from '../model/agent_studio';
+
+const studioBasePath = '/api/agent-studio/';
+
+/** Client for the `studio-v2` Agent Studio routes, which are fixed and unversioned. */
+@Injectable({ providedIn: 'root' })
+export class AgentStudioService extends BaseRestService {
+  listAgents(): Observable<AgentSummary[]> {
+    return this.http.get<AgentSummary[]>(this.studioUrl('agents'));
+  }
+
+  getDraft(agentName: string): Observable<AgentDraft> {
+    return this.http.get<AgentDraft>(this.studioUrl('agent'), { params: { agent_name: agentName } });
+  }
+
+  /** Every editable layer must be sent back: one missing from `draft` ends its binding. */
+  saveDraft(draft: AgentDraft): Observable<AgentDraft> {
+    return this.http.post<AgentDraft>(this.studioUrl('draft'), draft);
+  }
+
+  setEnabled(request: AgentSetEnabledRequest): Observable<AgentEnabledState> {
+    return this.http.post<AgentEnabledState>(this.studioUrl('enabled'), request);
+  }
+
+  /** Runs the saved draft, not unsaved form content. */
+  testDraft(request: AgentTestRequest): Observable<AgentTestResult> {
+    return this.http.post<AgentTestResult>(this.studioUrl('test'), request);
+  }
+
+  publish(request: AgentPublishRequest): Observable<AgentRelease> {
+    return this.http.post<AgentRelease>(this.studioUrl('publish'), request);
+  }
+
+  restore(request: AgentRestoreRequest): Observable<AgentRelease> {
+    return this.http.post<AgentRelease>(this.studioUrl('restore'), request);
+  }
+
+  reset(request: AgentResetRequest): Observable<AgentDraft> {
+    return this.http.post<AgentDraft>(this.studioUrl('reset'), request);
+  }
+
+  setDefault(request: AgentSetDefaultRequest): Observable<AgentSummary[]> {
+    return this.http.post<AgentSummary[]>(this.studioUrl('set-default'), request);
+  }
+
+  history(agentName: string): Observable<AgentRelease[]> {
+    return this.http.get<AgentRelease[]>(this.studioUrl('history'), { params: { agent_name: agentName } });
+  }
+
+  auditLog(agentName: string): Observable<AgentAuditEvent[]> {
+    return this.http.get<AgentAuditEvent[]>(this.studioUrl('audit'), { params: { agent_name: agentName } });
+  }
+
+  releaseSections(agentName: string, version: number): Observable<AgentReleaseSection[]> {
+    return this.http.get<AgentReleaseSection[]>(this.studioUrl('release-sections'), {
+      params: { agent_name: agentName, version: String(version) },
+    });
+  }
+
+  models(): Observable<StudioModel[]> {
+    return this.http.get<StudioModel[]>(this.studioUrl('models'));
+  }
+
+  private studioUrl(route: string): string {
+    return this.url(studioBasePath + route);
+  }
+}

package/src/agent/service/turn_stream.ts

@@ -0,0 +1,70 @@
+import { computed, signal } from '@angular/core';
+import { TURN_ERROR_CANCELED, TurnReplyFrame, TurnStreamStatus } from '../model/reply_frame';
+import { TurnEvent } from '../model/turn_event';
+
+const terminalStatuses: ReadonlySet<TurnStreamStatus> = new Set(['completed', 'canceled', 'failed']);
+
+/**
+ * Client-side state of one turn's reply stream. Transport stays the app's: it feeds frames to
+ * `accept`, reconnects from `cursor()`, and reports an expired replay window. One instance per
+ * turn; not injectable.
+ */
+export class TurnStream {
+  private readonly frames = signal<TurnReplyFrame[]>([]);
+  private readonly state = signal<TurnStreamStatus>('idle');
+  private readonly lastSequence = signal(0);
+
+  readonly status = this.state.asReadonly();
+  /** Last sequence rendered; a reconnect resumes after it. */
+  readonly cursor = this.lastSequence.asReadonly();
+  readonly events = computed<TurnEvent[]>(() => this.frames().flatMap((frame) => frame.events));
+  readonly finalFrame = computed(() => this.frames().find((frame) => frame.final));
+  readonly isTerminal = computed(() => terminalStatuses.has(this.state()));
+
+  constructor(readonly requestId: string) {}
+
+  /** Returns false for a frame of another turn, one already rendered, or one after the final. */
+  accept(frame: TurnReplyFrame): boolean {
+    if (frame.request_id !== this.requestId || this.isTerminal()) return false;
+    if (frame.sequence <= this.lastSequence()) return false;
+    this.lastSequence.set(frame.sequence);
+    this.append(frame);
+    return true;
+  }
+
+  /** The reconnect cursor fell behind the retained window; the app now reads the stored result. */
+  markReplayExpired(): void {
+    if (!this.isTerminal()) this.state.set('replay_expired');
+  }
+
+  /**
+   * A final frame rebuilt from the turn record: a payload or an error code, no intermediate
+   * events. It completes the turn whatever its sequence.
+   */
+  acceptStoredResult(frame: TurnReplyFrame): boolean {
+    if (frame.request_id !== this.requestId || !frame.final || this.isTerminal()) return false;
+    this.append(frame);
+    return true;
+  }
+
+  /** Cancel is a request: the turn stays `cancelling` until its final frame arrives. */
+  markCancelRequested(): void {
+    if (!this.isTerminal()) this.state.set('cancelling');
+  }
+
+  private append(frame: TurnReplyFrame): void {
+    this.frames.update((frames) => [...frames, frame]);
+    this.state.set(this.statusAfter(frame));
+  }
+
+  private statusAfter(frame: TurnReplyFrame): TurnStreamStatus {
+    if (frame.final) {
+      if (frame.error_code === TURN_ERROR_CANCELED) return 'canceled';
+      return frame.error_code ? 'failed' : 'completed';
+    }
+    if (this.state() === 'cancelling') return 'cancelling';
+    // approval_pending ends the delivery, not the turn: resumed frames follow on the same stream.
+    const last = frame.events[frame.events.length - 1];
+    return last?.kind === 'approval_pending' ? 'awaiting_approval' : 'streaming';
+  }
+}