@nauticana/sail 1.1.18 → 1.1.20

package/src/agent/component/turn_event_list.html

@@ -0,0 +1,101 @@
+<ol class="turn-events" aria-live="polite">
+  @for (item of items(); track $index) {
+    @switch (item.kind) {
+      @case ('text') {
+        <li class="turn-text">{{ item.text }}</li>
+      }
+      @case ('tool') {
+        <li class="turn-tool" [class.turn-tool--error]="item.errorClass !== undefined">
+          <div class="turn-tool__head">
+            <mat-icon aria-hidden="true">build</mat-icon>
+            <span class="turn-tool__id">{{ item.tool_id }}</span>
+            <span class="turn-tool__version">{{ item.tool_version }}</span>
+          </div>
+
+          @if (item.approval === 'pending') {
+            <p class="turn-tool__approval turn-tool__approval--pending" role="status">Waiting for approval</p>
+          } @else if (item.approval === 'resolved') {
+            <p class="turn-tool__approval" role="status">Approval: {{ item.decision }}</p>
+          }
+
+          @if (item.arguments !== undefined) {
+            <pre class="turn-tool__arguments">{{ item.arguments | json }}</pre>
+          }
+
+          @if (item.errorClass !== undefined) {
+            <p class="turn-tool__error" role="alert">Tool call failed: {{ item.errorClass }}</p>
+          } @else if (item.result) {
+            <pre class="turn-tool__output">{{ item.result.output | json }}</pre>
+          }
+
+          @if (item.effect; as effect) {
+            <div
+              class="turn-effect"
+              [class.turn-effect--satisfied]="effect.observation.status === 'satisfied'"
+              [class.turn-effect--violated]="effect.observation.status === 'violated'"
+              [class.turn-effect--unknown]="effect.observation.status === 'unknown'"
+            >
+              @switch (effect.observation.status) {
+                @case ('satisfied') {
+                  <span class="turn-effect__status">Effect confirmed</span>
+                }
+                @case ('violated') {
+                  <span class="turn-effect__status" role="alert">Effect not confirmed</span>
+                }
+                @case ('unknown') {
+                  <span class="turn-effect__status">Effect could not be verified</span>
+                }
+              }
+              @if (effect.observation.reconciled) {
+                <span class="turn-effect__reconciled">Already in place — nothing was sent again</span>
+              }
+              @if (effect.observation.reason) {
+                <p class="turn-effect__reason">{{ effect.observation.reason }}</p>
+              }
+              @if (effect.observation.evidence?.length) {
+                <ul class="turn-effect__evidence">
+                  @for (ref of effect.observation.evidence; track ref.URI) {
+                    <li>
+                      <span class="turn-ref__uri">{{ ref.URI }}</span>
+                      <span class="turn-ref__digest">{{ ref.Digest }}</span>
+                    </li>
+                  }
+                </ul>
+              }
+            </div>
+          }
+        </li>
+      }
+      @case ('evidence') {
+        <li class="turn-evidence">
+          <ul>
+            @for (ref of item.refs; track ref.id) {
+              <li>
+                <span class="turn-ref__source">{{ ref.source }}</span>
+                <span class="turn-ref__uri">{{ ref.uri || ref.object?.URI }}</span>
+                @if (ref.object?.Digest) {
+                  <span class="turn-ref__digest">{{ ref.object?.Digest }}</span>
+                }
+              </li>
+            }
+          </ul>
+        </li>
+      }
+      @case ('progress') {
+        <li class="turn-progress">
+          <span class="turn-progress__stage">{{ item.progress.stage }}</span>
+          @if (item.progress.message) {
+            <span class="turn-progress__message">{{ item.progress.message }}</span>
+          }
+        </li>
+      }
+      @case ('extension') {
+        @if (extensionTemplate(); as template) {
+          <li class="turn-extension">
+            <ng-container [ngTemplateOutlet]="template" [ngTemplateOutletContext]="{ $implicit: item.extension }" />
+          </li>
+        }
+      }
+    }
+  }
+</ol>

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);
+  }
+}