SDK Reference

Internal Platform SDK

Server-side module at platform/src/lib/sdk.ts. It uses Prisma directly, is not published as an npm package, and must not be imported by browser code.

This module is not authenticated by an API key. Authenticate the user and enforce route-level authorization and entitlements before calling methods that expose user or platform data. The optional region value is response metadata; it does not select a database or route network traffic.

# Internal platform server code only import { SkillOSClient } from '@/lib/sdk'; const client = new SkillOSClient({ region: "global" });

.activateSkill()

activateSkill(options: ActivateSkillOptions): Promise<SkillActivationResponse>

Reads and returns the SDS system prompt for a skill from the server-side registry. This internal method does not perform caller authentication or entitlement checks; allowed means the artifact loaded, not that the caller is entitled to use it.

Parameters

options.skillName string The skill slug to load

Returns

{ skillName, version, systemPrompt, allowed, region } — allowed reports artifact loading only

Throws

SKILL_NOT_FOUND · SKILL_CONTENT_MISSING

const skill = await client.activateSkill({ skillName: "senior-rails-engineer" });
console.log(skill.systemPrompt); // Full SDS system prompt

.listSkills()

listSkills(options?: ListSkillsOptions): Promise<SkillSummary[]>

Queries the live registry. Supports filtering by tier, domain, access level, and free-text search.

Parameters

`options.tier`	`number`	SDS tier filter (0–4)
`options.domain`	`string`	Vertical/domain filter
`options.accessLevel`	`string`	ordinary \| premium \| enterprise_only
`options.search`	`string`	Free-text search against display name or domain

Returns

SkillSummary[] — { skillName, displayName, version, tier, domain, accessLevel, description? }

Throws

REGISTRY_UNAVAILABLE

const skills = await client.listSkills({ tier: 2, domain: "fintech" });

.createWorkflow()

createWorkflow(options: CreateWorkflowOptions): Promise<WorkflowResponse>

Persists a draft workflow definition. Workflow execution is a separate operation.

Parameters

`options.name`	`string`	Workflow name, at least three characters
`options.skills`	`string[]`	One or more skill names
`options.outcome`	`string`	Expected workflow outcome
`options.userId`	`string`	Owning user ID

Returns

{ workflowId, name, status }

Throws

VALIDATION_ERROR · WORKFLOW_PERSIST_FAILED

const wf = await client.createWorkflow({
  name: "Contract Review Pipeline",
  skills: ["legal-specialist", "fintech-compliance"],
  outcome: "Reviewed contract with compliance findings",
  userId: "user-cuid",
  requiresApproval: true,
});

.runWorkflow()

runWorkflow(options: RunWorkflowOptions): Promise<WorkflowRunResponse>

Creates an owner-scoped WorkflowRun. Approval-gated runs return as awaiting_approval and are not dispatched. Other eligible runs return queued only after Inngest accepts the event; dispatch failures return failed, the worker's current run status, or dispatch_unconfirmed.

Parameters

`options.workflowId`	`string`	The workflow ID returned by createWorkflow
`options.userId`	`string`	Requesting user ID
`options.input`	`Record<string, unknown>`	Optional runtime input variables

Returns

{ runId, workflowId, status, queuedAt }

Throws

EXECUTION_DISABLED · WORKFLOW_NOT_FOUND · WORKFLOW_ARCHIVED · WORKFLOW_NOT_READY · RUN_QUOTA_EXCEEDED · RUN_QUOTA_UNAVAILABLE are SkillOSError codes; database errors may propagate, and queue delivery failures are returned in status and dispatchState.

const run = await client.runWorkflow({ workflowId: wf.workflowId, userId: "user-cuid", input: { contractText } });
if (run.status === "awaiting_approval") {
  console.log("An owner must approve this run before it can execute.");
} else if (run.status === "queued") {
  console.log("The worker queue accepted the run.");
} else {
  console.error("Run dispatch needs attention:", run.status, run.dispatchState);
}

.getProjectMemory()

getProjectMemory(userId: string, query?): Promise<Array<{ id, title, category, content, tags, isSeeded, timestamp, region }>>

Queries the project memory layer. Supports tag matching, multi-field case-insensitive search, and native PostgreSQL array operators.

Parameters

`userId`	`string`	Owner whose private and globally seeded records may be returned
`query.tag`	`string`	Single tag match
`query.tags`	`string[]`	Any-of tag match; ignored when tag is set
`query.search`	`string`	Case-insensitive search across title, content, and tags

Returns

Records owned by the user plus globally seeded records, newest first

Throws

Database errors propagate from Prisma

const memories = await client.getProjectMemory("user-cuid", { tags: ["decision", "architecture"] });

.ingestKnowledge()

ingestKnowledge(options: IngestKnowledgeOptions): Promise<KnowledgeIngestResponse>

Queues URL ingestion through Inngest or synchronously persists plaintext knowledge.

Parameters

`options.url`	`string`	Optional URL; when set, text is ignored
`options.text`	`string`	Optional raw plaintext; provide URL or text
`options.title`	`string`	Required document title
`options.authorityScore`	`number`	Optional authority score
`options.ttlDays`	`number`	Optional document TTL in days

Returns

{ status: 'queued' | 'persisted', documentId? }

Throws

VALIDATION_ERROR · KNOWLEDGE_PERSIST_FAILED

await client.ingestKnowledge({
  url: "https://example.gov/ai-regulation-2026.pdf",
  authorityScore: 92,
  ttlDays: 90,
});

.getDecisionSummary()

getDecisionSummary(): Promise<DecisionSummaryResponse>

Aggregates decision counts. The alignment rate remains null until at least ten evaluated decisions exist.

Returns

{ total, aligned, alignmentRate, overrideCount, inconclusiveCount }

Throws

DECISION_LEDGER_UNAVAILABLE

const summary = await client.getDecisionSummary();
  console.log(summary.alignmentRate); // percentage or null until evidence threshold

.checkEntitlement()

checkEntitlement(options: CheckEntitlementOptions): Promise<EntitlementSummary>

Checks an explicitly supplied user, plan, and skill access level against entitlements.

Parameters

`options.userId`	`string`	User ID
`options.plan`	`Plan`	Current plan
`options.skillAccessLevel`	`string`	ordinary \| premium \| enterprise_only
`options.skillName`	`string`	Optional skill slug

Returns

{ allowed, reason?, remaining?, dailyQuota?, resetAt? }

Throws

ENTITLEMENT_CHECK_FAILED

const { allowed } = await client.checkEntitlement({ userId: "user-cuid", plan: "pro", skillAccessLevel: "premium", skillName: "fintech-compliance" });
if (!allowed) redirect("/pricing");

Typed Error Codes

These are errors wrapped by the internal SDK. Some database and Inngest failures are not wrapped and may propagate from their clients.

Code	Description
`SKILL_NOT_FOUND`	The requested skill is absent from the registry artifacts
`SKILL_CONTENT_MISSING`	The skill exists but has no loadable content
`REGISTRY_UNAVAILABLE`	The registry database query failed
`VALIDATION_ERROR`	Workflow or knowledge input failed validation
`WORKFLOW_PERSIST_FAILED`	Workflow creation failed in the database
`WORKFLOW_NOT_FOUND`	No workflow matches the requested ID
`KNOWLEDGE_PERSIST_FAILED`	Text knowledge could not be persisted
`ENTITLEMENT_CHECK_FAILED`	The entitlement database check failed
`DECISION_LEDGER_UNAVAILABLE`	Decision summary query failed

CLI Reference SDS Standard

Documentation

SDK Reference

Internal Platform SDK

Server-side module at platform/src/lib/sdk.ts. It uses Prisma directly, is not published as an npm package, and must not be imported by browser code.

# Internal platform server code only import { SkillOSClient } from '@/lib/sdk'; const client = new SkillOSClient({ region: "global" });

.activateSkill()

activateSkill(options: ActivateSkillOptions): Promise<SkillActivationResponse>

Parameters

options.skillName string The skill slug to load

Returns

{ skillName, version, systemPrompt, allowed, region } — allowed reports artifact loading only

Throws

SKILL_NOT_FOUND · SKILL_CONTENT_MISSING

const skill = await client.activateSkill({ skillName: "senior-rails-engineer" });
console.log(skill.systemPrompt); // Full SDS system prompt

.listSkills()

listSkills(options?: ListSkillsOptions): Promise<SkillSummary[]>

Queries the live registry. Supports filtering by tier, domain, access level, and free-text search.

Parameters

`options.tier`	`number`	SDS tier filter (0–4)
`options.domain`	`string`	Vertical/domain filter
`options.accessLevel`	`string`	ordinary \| premium \| enterprise_only
`options.search`	`string`	Free-text search against display name or domain

Returns

SkillSummary[] — { skillName, displayName, version, tier, domain, accessLevel, description? }

Throws

REGISTRY_UNAVAILABLE

const skills = await client.listSkills({ tier: 2, domain: "fintech" });

.createWorkflow()

createWorkflow(options: CreateWorkflowOptions): Promise<WorkflowResponse>

Persists a draft workflow definition. Workflow execution is a separate operation.

Parameters

`options.name`	`string`	Workflow name, at least three characters
`options.skills`	`string[]`	One or more skill names
`options.outcome`	`string`	Expected workflow outcome
`options.userId`	`string`	Owning user ID

Returns

{ workflowId, name, status }

Throws

VALIDATION_ERROR · WORKFLOW_PERSIST_FAILED

const wf = await client.createWorkflow({
  name: "Contract Review Pipeline",
  skills: ["legal-specialist", "fintech-compliance"],
  outcome: "Reviewed contract with compliance findings",
  userId: "user-cuid",
  requiresApproval: true,
});

.runWorkflow()

runWorkflow(options: RunWorkflowOptions): Promise<WorkflowRunResponse>

Parameters

`options.workflowId`	`string`	The workflow ID returned by createWorkflow
`options.userId`	`string`	Requesting user ID
`options.input`	`Record<string, unknown>`	Optional runtime input variables

Returns

{ runId, workflowId, status, queuedAt }

Throws

EXECUTION_DISABLED · WORKFLOW_NOT_FOUND · WORKFLOW_ARCHIVED · WORKFLOW_NOT_READY · RUN_QUOTA_EXCEEDED · RUN_QUOTA_UNAVAILABLE are SkillOSError codes; database errors may propagate, and queue delivery failures are returned in status and dispatchState.

const run = await client.runWorkflow({ workflowId: wf.workflowId, userId: "user-cuid", input: { contractText } });
if (run.status === "awaiting_approval") {
  console.log("An owner must approve this run before it can execute.");
} else if (run.status === "queued") {
  console.log("The worker queue accepted the run.");
} else {
  console.error("Run dispatch needs attention:", run.status, run.dispatchState);
}

.getProjectMemory()

getProjectMemory(userId: string, query?): Promise<Array<{ id, title, category, content, tags, isSeeded, timestamp, region }>>

Queries the project memory layer. Supports tag matching, multi-field case-insensitive search, and native PostgreSQL array operators.

Parameters

`userId`	`string`	Owner whose private and globally seeded records may be returned
`query.tag`	`string`	Single tag match
`query.tags`	`string[]`	Any-of tag match; ignored when tag is set
`query.search`	`string`	Case-insensitive search across title, content, and tags

Returns

Records owned by the user plus globally seeded records, newest first

Throws

Database errors propagate from Prisma

const memories = await client.getProjectMemory("user-cuid", { tags: ["decision", "architecture"] });

.ingestKnowledge()

ingestKnowledge(options: IngestKnowledgeOptions): Promise<KnowledgeIngestResponse>

Queues URL ingestion through Inngest or synchronously persists plaintext knowledge.

Parameters

`options.url`	`string`	Optional URL; when set, text is ignored
`options.text`	`string`	Optional raw plaintext; provide URL or text
`options.title`	`string`	Required document title
`options.authorityScore`	`number`	Optional authority score
`options.ttlDays`	`number`	Optional document TTL in days

Returns

{ status: 'queued' | 'persisted', documentId? }

Throws

VALIDATION_ERROR · KNOWLEDGE_PERSIST_FAILED

await client.ingestKnowledge({
  url: "https://example.gov/ai-regulation-2026.pdf",
  authorityScore: 92,
  ttlDays: 90,
});

.getDecisionSummary()

getDecisionSummary(): Promise<DecisionSummaryResponse>

Aggregates decision counts. The alignment rate remains null until at least ten evaluated decisions exist.

Returns

{ total, aligned, alignmentRate, overrideCount, inconclusiveCount }

Throws

DECISION_LEDGER_UNAVAILABLE

const summary = await client.getDecisionSummary();
  console.log(summary.alignmentRate); // percentage or null until evidence threshold

.checkEntitlement()

checkEntitlement(options: CheckEntitlementOptions): Promise<EntitlementSummary>

Checks an explicitly supplied user, plan, and skill access level against entitlements.

Parameters

`options.userId`	`string`	User ID
`options.plan`	`Plan`	Current plan
`options.skillAccessLevel`	`string`	ordinary \| premium \| enterprise_only
`options.skillName`	`string`	Optional skill slug

Returns

{ allowed, reason?, remaining?, dailyQuota?, resetAt? }

Throws

ENTITLEMENT_CHECK_FAILED

const { allowed } = await client.checkEntitlement({ userId: "user-cuid", plan: "pro", skillAccessLevel: "premium", skillName: "fintech-compliance" });
if (!allowed) redirect("/pricing");

Typed Error Codes

These are errors wrapped by the internal SDK. Some database and Inngest failures are not wrapped and may propagate from their clients.

Code	Description
`SKILL_NOT_FOUND`	The requested skill is absent from the registry artifacts
`SKILL_CONTENT_MISSING`	The skill exists but has no loadable content
`REGISTRY_UNAVAILABLE`	The registry database query failed
`VALIDATION_ERROR`	Workflow or knowledge input failed validation
`WORKFLOW_PERSIST_FAILED`	Workflow creation failed in the database
`WORKFLOW_NOT_FOUND`	No workflow matches the requested ID
`KNOWLEDGE_PERSIST_FAILED`	Text knowledge could not be persisted
`ENTITLEMENT_CHECK_FAILED`	The entitlement database check failed
`DECISION_LEDGER_UNAVAILABLE`	Decision summary query failed

CLI Reference SDS Standard