osuite 2.9.0 → 2.9.1

package/osuite.js

@@ -1,10 +1,505 @@
-export {
-  default,
-  DashClaw,
-  OSuite,
-  Osuite,
-  ApprovalDeniedError,
-  GuardBlockedError,
-  PCAA_CHECKPOINTS,
-  buildPcaaCheckpointStates,
-} from './dashclaw.js';
+import { buildReviewSurface } from './reviewSurface.js';
+
+class ApprovalDeniedError extends Error {
+  constructor(message, decision) {
+    super(message);
+    this.name = 'ApprovalDeniedError';
+    this.decision = decision;
+  }
+}
+
+class GuardBlockedError extends Error {
+  constructor(decision) {
+    super(decision?.reason || 'Action blocked by policy');
+    this.name = 'GuardBlockedError';
+    this.decision = decision;
+  }
+}
+
+class OSuite {
+  constructor({ baseUrl, apiKey, agentId, agentKeyId = null, provenanceVersion = 'osuite-prov-v1' } = {}) {
+    if (!baseUrl) throw new Error('baseUrl is required');
+    if (!apiKey) throw new Error('apiKey is required');
+    if (!agentId) throw new Error('agentId is required');
+
+    this.baseUrl = String(baseUrl).replace(/\/$/, '');
+    this.apiKey = apiKey;
+    this.agentId = agentId;
+    this.agentKeyId = agentKeyId;
+    this.provenanceVersion = provenanceVersion;
+  }
+
+  _withProvenance(payload = {}) {
+    const body = { ...payload };
+    const signature = body.agentSignature || body.agent_signature || body._signature || null;
+    delete body.agentSignature;
+    delete body.agent_signature;
+
+    if (signature) body._signature = signature;
+    if (body.agent_key_id === undefined && this.agentKeyId) body.agent_key_id = this.agentKeyId;
+    if (body.provenance_version === undefined && this.provenanceVersion) {
+      body.provenance_version = this.provenanceVersion;
+    }
+    return body;
+  }
+
+  async _request(path, method = 'GET', body = null, params = null) {
+    let url = `${this.baseUrl}${path}`;
+    if (params) {
+      const query = new URLSearchParams();
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null && value !== '') query.set(key, String(value));
+      });
+      const qs = query.toString();
+      if (qs) url += `?${qs}`;
+    }
+
+    const response = await fetch(url, {
+      method,
+      headers: {
+        'content-type': 'application/json',
+        'x-api-key': this.apiKey,
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+
+    const text = await response.text();
+    let data = {};
+    if (text) {
+      try {
+        data = JSON.parse(text);
+      } catch {
+        data = { raw: text };
+      }
+    }
+
+    if (!response.ok) {
+      if (response.status === 403 && data.decision?.decision === 'block') {
+        throw new GuardBlockedError(data.decision);
+      }
+      const error = new Error(data.reason || data.error || `Request failed with status ${response.status}`);
+      error.status = response.status;
+      error.details = data.details;
+      error.response = data;
+      throw error;
+    }
+
+    return data;
+  }
+
+  async guard(context = {}) {
+    return this._request('/api/guard', 'POST', this._withProvenance({
+      ...context,
+      agent_id: context.agent_id || this.agentId,
+    }));
+  }
+
+  async createAction(action = {}) {
+    return this._request('/api/actions', 'POST', this._withProvenance({
+      ...action,
+      agent_id: action.agent_id || this.agentId,
+    }));
+  }
+
+  async updateOutcome(actionId, outcome = {}) {
+    return this._request(`/api/actions/${encodeURIComponent(actionId)}`, 'PATCH', {
+      ...outcome,
+      timestamp_end: outcome.timestamp_end || new Date().toISOString(),
+    });
+  }
+
+  async getActions(filters = {}) {
+    return this._request('/api/actions', 'GET', null, filters);
+  }
+
+  async getAction(actionId) {
+    return this._request(`/api/actions/${encodeURIComponent(actionId)}`, 'GET');
+  }
+
+  async getPendingApprovals(limit = 20, offset = 0) {
+    return this.getActions({ status: 'pending_approval', limit, offset });
+  }
+
+  async approveAction(actionId, decision, reasoning = null) {
+    return this._request(`/api/approvals/${encodeURIComponent(actionId)}`, 'POST', {
+      decision,
+      ...(reasoning ? { reasoning } : {}),
+    });
+  }
+
+  async waitForApproval(actionId, { timeout = 300000, interval = 5000, print = true } = {}) {
+    const startedAt = Date.now();
+    let wasPending = false;
+    let printed = false;
+
+    while (Date.now() - startedAt < timeout) {
+      const payload = await this.getAction(actionId);
+      const action = payload.action || payload;
+
+      if (print && !printed) {
+        printed = true;
+        process.stdout.write(`\n${buildReviewSurface(action, { baseUrl: this.baseUrl })}\n\nWaiting for approval... Ctrl+C to abort.\n\n`);
+      }
+
+      if (action.status === 'pending_approval') wasPending = true;
+      if (action.approved_by || action.approved_at) return action;
+      if (action.status === 'failed' || action.status === 'cancelled') {
+        throw new ApprovalDeniedError(action.error_message || 'Operator denied the action.', action.status);
+      }
+      if (wasPending && action.status !== 'pending_approval') {
+        throw new Error(`Action ${actionId} left pending_approval without explicit approval metadata.`);
+      }
+      if (!wasPending && action.status === 'running') return action;
+
+      await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+
+    throw new Error(`Timed out waiting for approval of action ${actionId}`);
+  }
+
+  async recordAssumption(assumption = {}) {
+    return this._request('/api/assumptions', 'POST', assumption);
+  }
+
+  async registerAssumption(assumption = {}) {
+    return this.recordAssumption({
+      agent_id: this.agentId,
+      ...assumption,
+    });
+  }
+
+  async getAssumption(assumptionId) {
+    return this._request(`/api/assumptions/${encodeURIComponent(assumptionId)}`);
+  }
+
+  async registerOpenLoop(actionId, loopType, description, metadata = null) {
+    const payload = typeof actionId === 'object'
+      ? { agent_id: this.agentId, ...actionId }
+      : { action_id: actionId, loop_type: loopType, description, metadata, agent_id: this.agentId };
+    return this._request('/api/actions/loops', 'POST', payload);
+  }
+
+  async getOpenLoops(filters = {}) {
+    return this._request('/api/actions/loops', 'GET', null, filters);
+  }
+
+  async resolveOpenLoop(loopId, status, resolution = null) {
+    return this._request(`/api/actions/loops/${encodeURIComponent(loopId)}`, 'PATCH', { status, resolution });
+  }
+
+  async getSignals() {
+    return this._request('/api/signals');
+  }
+
+  async reportTokenUsage(usage = {}) {
+    return this._request('/api/actions', 'POST', {
+      agent_id: this.agentId,
+      action_type: 'token_usage',
+      status: 'completed',
+      declared_goal: 'Report token usage',
+      ...usage,
+    });
+  }
+
+  async heartbeat(status = 'online', metadata = null) {
+    return this._request('/api/agents/heartbeat', 'POST', {
+      agent_id: this.agentId,
+      status,
+      metadata,
+    });
+  }
+
+  async reportConnections(connections = []) {
+    return this._request('/api/agents/connections', 'POST', {
+      agent_id: this.agentId,
+      connections,
+    });
+  }
+
+  async getActionTrace(actionId) {
+    return this._request(`/api/actions/${encodeURIComponent(actionId)}/trace`);
+  }
+
+  async getGovernanceProof({ actionId, format } = {}) {
+    return this._request('/api/governance/proof', 'GET', null, {
+      ...(actionId ? { action_id: actionId } : {}),
+      ...(format ? { format } : {}),
+    });
+  }
+
+  async getGovernanceProofBundle({ actionId } = {}) {
+    return this.getGovernanceProof({ actionId, format: 'bundle' });
+  }
+
+  async verifyGovernanceProof(actionId) {
+    return this._request('/api/governance/proof/verify', 'POST', { action_id: actionId });
+  }
+
+  async exportProof({ actionId, bundleId } = {}) {
+    return this._request('/api/proof/export', 'GET', null, {
+      ...(actionId ? { action_id: actionId } : {}),
+      ...(bundleId ? { bundle_id: bundleId } : {}),
+    });
+  }
+
+  async getComplianceEvidence(params = {}) {
+    return this._request('/api/compliance/evidence', 'GET', null, params);
+  }
+
+  async getPcaaHealth(params = {}) {
+    return this._request('/api/governance/proof', 'GET', null, {
+      view: 'pcaa_health',
+      ...params,
+    });
+  }
+
+  async getPcaaAction(actionId) {
+    return this._request(`/api/actions/${encodeURIComponent(actionId)}`, 'GET', null, {
+      view: 'pcaa',
+    });
+  }
+
+  async events({ signal } = {}) {
+    const response = await fetch(`${this.baseUrl}/api/stream`, {
+      headers: { 'x-api-key': this.apiKey },
+      signal,
+    });
+    if (!response.ok) throw new Error(`Event stream failed with status ${response.status}`);
+    return response;
+  }
+
+  async createScorer(name, scorer_type, config = null, description = null) {
+    return this._request('/api/evaluations/scorers', 'POST', { name, scorer_type, config, description });
+  }
+
+  async createScoringProfile(profile) {
+    return this._request('/api/scoring/profiles', 'POST', profile);
+  }
+
+  async listScoringProfiles(filters = {}) {
+    return this._request('/api/scoring/profiles', 'GET', null, filters);
+  }
+
+  async getScoringProfile(profileId) {
+    return this._request(`/api/scoring/profiles/${encodeURIComponent(profileId)}`);
+  }
+
+  async updateScoringProfile(profileId, updates) {
+    return this._request(`/api/scoring/profiles/${encodeURIComponent(profileId)}`, 'PATCH', updates);
+  }
+
+  async deleteScoringProfile(profileId) {
+    return this._request(`/api/scoring/profiles/${encodeURIComponent(profileId)}`, 'DELETE');
+  }
+
+  async addScoringDimension(profileId, dimension) {
+    return this._request(`/api/scoring/profiles/${encodeURIComponent(profileId)}/dimensions`, 'POST', dimension);
+  }
+
+  async updateScoringDimension(profileId, dimensionId, updates) {
+    return this._request(`/api/scoring/profiles/${encodeURIComponent(profileId)}/dimensions/${encodeURIComponent(dimensionId)}`, 'PATCH', updates);
+  }
+
+  async deleteScoringDimension(profileId, dimensionId) {
+    return this._request(`/api/scoring/profiles/${encodeURIComponent(profileId)}/dimensions/${encodeURIComponent(dimensionId)}`, 'DELETE');
+  }
+
+  async scoreWithProfile(profileId, action) {
+    return this._request('/api/scoring/score', 'POST', { profile_id: profileId, action });
+  }
+
+  async batchScoreWithProfile(profileId, actions) {
+    return this._request('/api/scoring/score', 'POST', { profile_id: profileId, actions });
+  }
+
+  async getProfileScores(filters = {}) {
+    return this._request('/api/scoring/score', 'GET', null, filters);
+  }
+
+  async getProfileScoreStats(profileId) {
+    return this._request('/api/scoring/score', 'GET', null, { profile_id: profileId, view: 'stats' });
+  }
+
+  async createRiskTemplate(template) {
+    return this._request('/api/scoring/risk-templates', 'POST', template);
+  }
+
+  async listRiskTemplates(filters = {}) {
+    return this._request('/api/scoring/risk-templates', 'GET', null, filters);
+  }
+
+  async updateRiskTemplate(templateId, updates) {
+    return this._request(`/api/scoring/risk-templates/${encodeURIComponent(templateId)}`, 'PATCH', updates);
+  }
+
+  async deleteRiskTemplate(templateId) {
+    return this._request(`/api/scoring/risk-templates/${encodeURIComponent(templateId)}`, 'DELETE');
+  }
+
+  async autoCalibrate(options = {}) {
+    return this._request('/api/scoring/calibrate', 'POST', options);
+  }
+
+  async sendMessage({ to, type, subject, body, threadId, urgent, actionId }) {
+    return this._request('/api/messages', 'POST', {
+      from_agent_id: this.agentId,
+      to_agent_id: to,
+      message_type: type,
+      subject,
+      body,
+      thread_id: threadId,
+      urgent,
+      action_id: actionId,
+    });
+  }
+
+  async getInbox({ type, unread, limit } = {}) {
+    return this._request('/api/messages', 'GET', null, {
+      agent_id: this.agentId,
+      direction: 'inbox',
+      ...(type ? { type } : {}),
+      ...(unread != null ? { unread } : {}),
+      ...(limit ? { limit } : {}),
+    });
+  }
+
+  async createHandoff(handoff) {
+    return this._request('/api/_archive/handoffs', 'POST', { agent_id: this.agentId, ...handoff });
+  }
+
+  async getHandoffs(filters = {}) {
+    return this._request('/api/_archive/handoffs', 'GET', null, {
+      agent_id: this.agentId,
+      ...filters,
+    });
+  }
+
+  async getLatestHandoff() {
+    return this._request('/api/_archive/handoffs', 'GET', null, { agent_id: this.agentId, latest: 'true' });
+  }
+
+  async scanPromptInjection(text, { source } = {}) {
+    return this._request('/api/security/prompt-injection', 'POST', { text, source, agent_id: this.agentId });
+  }
+
+  async scanContent(text, destination = null) {
+    return this._request('/api/security/scan', 'POST', {
+      text,
+      destination,
+      agent_id: this.agentId,
+      store: false,
+    });
+  }
+
+  async submitFeedback({ action_id, rating, comment, category, tags, metadata }) {
+    return this._request('/api/feedback', 'POST', {
+      action_id,
+      agent_id: this.agentId,
+      rating,
+      comment,
+      category,
+      tags,
+      metadata,
+    });
+  }
+
+  async createThread(thread) {
+    return this._request('/api/messages/threads', 'POST', {
+      created_by: this.agentId,
+      participants: [this.agentId],
+      ...thread,
+    });
+  }
+
+  async getThreads(filters = {}) {
+    return this._request('/api/messages/threads', 'GET', null, {
+      agent_id: this.agentId,
+      ...filters,
+    });
+  }
+
+  async addThreadEntry(threadId, content, entryType) {
+    return this._request(`/api/context/threads/${encodeURIComponent(threadId)}/entries`, 'POST', {
+      content,
+      entry_type: entryType,
+    });
+  }
+
+  async closeThread(threadId, summary) {
+    return this._request('/api/messages/threads', 'PATCH', {
+      thread_id: threadId,
+      status: 'resolved',
+      ...(summary ? { summary } : {}),
+    });
+  }
+
+  async saveSnippet(snippet = {}) {
+    return this._request('/api/_archive/snippets', 'POST', {
+      agent_id: this.agentId,
+      ...snippet,
+    });
+  }
+
+  async getSnippet(snippetId) {
+    return this._request(`/api/_archive/snippets/${encodeURIComponent(snippetId)}`);
+  }
+
+  async setPreference(preference = {}) {
+    return this._request('/api/_archive/preferences', 'POST', {
+      type: 'preference',
+      agent_id: this.agentId,
+      ...preference,
+    });
+  }
+
+  async getPreferenceSummary() {
+    return this._request('/api/_archive/preferences', 'GET', null, {
+      type: 'summary',
+      agent_id: this.agentId,
+    });
+  }
+
+  async getDailyDigest(date = null) {
+    return this._request('/api/_archive/digest', 'GET', null, {
+      agent_id: this.agentId,
+      ...(date ? { date } : {}),
+    });
+  }
+
+  async getSentMessages({ type, threadId, limit } = {}) {
+    return this._request('/api/messages', 'GET', null, {
+      agent_id: this.agentId,
+      direction: 'sent',
+      ...(type ? { type } : {}),
+      ...(threadId ? { thread_id: threadId } : {}),
+      ...(limit ? { limit } : {}),
+    });
+  }
+
+  async getWebhooks() {
+    return this._request('/api/webhooks');
+  }
+
+  async syncState(state) {
+    return this._request('/api/sync', 'POST', { agent_id: this.agentId, ...state });
+  }
+
+  actionContext(actionId) {
+    return {
+      sendMessage: (message) => this.sendMessage({ ...message, actionId }),
+      recordAssumption: (assumption) => this.recordAssumption({ ...assumption, action_id: actionId }),
+      updateOutcome: (outcome) => this.updateOutcome(actionId, outcome),
+    };
+  }
+
+  renderReview(action, options = {}) {
+    return buildReviewSurface(action, { baseUrl: this.baseUrl, ...options });
+  }
+}
+
+const DashClaw = OSuite;
+const Osuite = OSuite;
+const OpenClawAgent = OSuite;
+
+export default OSuite;
+export { ApprovalDeniedError, DashClaw, GuardBlockedError, OSuite, Osuite, OpenClawAgent, buildReviewSurface };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "osuite",
-  "version": "2.9.0",
-  "description": "OSuite governance runtime for AI agents. Intercept, govern, and verify agent actions.",
+  "version": "2.9.1",
+  "description": "OSuite governed action SDK for AI agents. Approve, replay, prove, and verify runtime decisions.",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -23,8 +23,8 @@
   },
   "files": [
     "cli.js",
+    "reviewSurface.js",
     "osuite.js",
-    "dashclaw.js",
     "index.cjs",
     "LICENSE",
     "README.md",
@@ -35,16 +35,10 @@
     "decision-infrastructure",
     "agent-governance",
     "guardrails",
-    "dashclaw",
     "osuite"
   ],
   "author": "OSuite",
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ucsandman/DashClaw.git",
-    "directory": "sdk"
-  },
   "engines": {
     "node": ">=18.0.0"
   },

package/reviewSurface.js

@@ -0,0 +1,131 @@
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+const CYAN = '\x1b[36m';
+
+function colorize(value, color, enabled) {
+  return enabled ? `${color}${value}${RESET}` : value;
+}
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function getActionId(action = {}) {
+  return action.action_id || action.id || action.actionId || 'unknown-action';
+}
+
+function getScore(action = {}) {
+  const summary = action.decision_summary || action.scorecard || action.risk_presentation || {};
+  return summary.policyScore ?? summary.rawScore ?? action.risk_score ?? action.agent_risk_score ?? null;
+}
+
+function getGrade(score) {
+  if (score == null || Number.isNaN(Number(score))) return 'Unscored';
+  const numeric = Number(score);
+  if (numeric >= 85) return 'Critical';
+  if (numeric >= 70) return 'High';
+  if (numeric >= 45) return 'Moderate';
+  return 'Low';
+}
+
+function getGradeColor(grade) {
+  if (grade === 'Critical' || grade === 'High') return RED;
+  if (grade === 'Moderate') return YELLOW;
+  return GREEN;
+}
+
+function line(label, value) {
+  if (value == null || value === '') return null;
+  return `${label.padEnd(21)} ${value}`;
+}
+
+function normalizeDecisionSummary(action = {}) {
+  const summary = action.decision_summary || action.scorecard || action.risk_presentation || {};
+  const understood = summary.understoodAction || summary.understood_action || {};
+  const evidence = summary.evidenceConfidence || summary.evidence_confidence || {};
+  const control = summary.controlSummary || summary.control_summary || {};
+  const dimensions = summary.dimensions || summary.scoreDimensions || summary.score_dimensions || [];
+
+  return {
+    understood,
+    evidence,
+    control,
+    dimensions: asArray(dimensions),
+    missingEvidence: asArray(summary.missingEvidence || summary.missing_evidence),
+  };
+}
+
+export function buildReviewSurface(action = {}, options = {}) {
+  const color = options.color ?? !process.env.NO_COLOR;
+  const score = getScore(action);
+  const grade = action.decision_grade || action.grade || getGrade(score);
+  const gradeColor = getGradeColor(grade);
+  const summary = normalizeDecisionSummary(action);
+  const actionId = getActionId(action);
+  const title = `OSuite Decision Review`;
+  const scoreText = score == null ? 'not scored' : `${Math.round(Number(score))}/100`;
+  const understoodSummary = summary.understood.summary
+    || summary.understood.label
+    || action.declared_goal
+    || action.action_type
+    || 'No action summary was provided.';
+  const evidenceLabel = summary.evidence.label
+    || (summary.evidence.score != null ? `${summary.evidence.score}/100` : null)
+    || 'Evidence confidence not provided';
+  const controlLabel = summary.control.label
+    || summary.control.summary
+    || action.effective_decision
+    || action.status
+    || 'No control posture provided';
+
+  const rows = [
+    line('Action ID', actionId),
+    line('Agent', action.agent_name || action.agent_id),
+    line('Action type', action.action_type),
+    line('Decision', action.effective_decision || action.decision || action.status),
+    line('Score', `${scoreText} (${colorize(grade, gradeColor, color)})`),
+    line('OSuite understood', understoodSummary),
+    line('Evidence confidence', evidenceLabel),
+    line('Control posture', controlLabel),
+  ].filter(Boolean);
+
+  const dimensionLines = summary.dimensions.length
+    ? [
+        '',
+        colorize('Score dimensions', BOLD, color),
+        ...summary.dimensions.map((dimension) => {
+          const label = dimension.label || dimension.id || 'dimension';
+          const value = dimension.score ?? dimension.value ?? '-';
+          const reason = dimension.summary || dimension.reason || '';
+          return `  ${label.padEnd(18)} ${String(value).padStart(3)}${reason ? `  ${colorize(reason, DIM, color)}` : ''}`;
+        }),
+      ]
+    : [];
+
+  const missingEvidenceLines = summary.missingEvidence.length
+    ? [
+        '',
+        colorize('Missing evidence', BOLD, color),
+        ...summary.missingEvidence.map((item) => `  - ${item.label || item.id || item}`),
+      ]
+    : [];
+
+  const replayUrl = options.baseUrl ? `${String(options.baseUrl).replace(/\/$/, '')}/replay/${actionId}` : null;
+  const footer = replayUrl ? ['', `${colorize('Replay', BOLD, color)} ${replayUrl}`] : [];
+
+  return [
+    colorize(title, `${BOLD}${CYAN}`, color),
+    colorize('Route. Review. Prove.', DIM, color),
+    '',
+    ...rows,
+    ...dimensionLines,
+    ...missingEvidenceLines,
+    ...footer,
+  ].join('\n');
+}
+
+export default buildReviewSurface;

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Osuite
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.