@ultrst-armada/kloks 1.22.1 → 1.23.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "schema": 1,
3
3
  "packageName": "@ultrst-armada/kloks",
4
- "version": "1.22.1",
5
- "sourceCommit": "5b69ae1bba83c72c0b44bc8492928a805948872a",
4
+ "version": "1.23.0",
5
+ "sourceCommit": "dd84756182c810b22853ab5f91c6a9cbf1fa103e",
6
6
  "releaseWorkflow": "npm Release",
7
- "workflowRunId": "41112820841"
7
+ "workflowRunId": "41207095076"
8
8
  }
package/index.d.ts CHANGED
@@ -7,3 +7,4 @@ export * from './packages/orchestrations/dist/index.d.ts';
7
7
  export * from './packages/contracts/dist/index.d.ts';
8
8
  export * from './packages/fod/dist/index.d.ts';
9
9
  export * from './packages/aiko/dist/index.d.ts';
10
+ export * from './packages/semantic-runtime/dist/index.d.ts';
package/index.js CHANGED
@@ -7,3 +7,4 @@ export * from './packages/orchestrations/dist/index.js';
7
7
  export * from './packages/contracts/dist/index.js';
8
8
  export * from './packages/fod/dist/index.js';
9
9
  export * from './packages/aiko/dist/index.js';
10
+ export * from './packages/semantic-runtime/dist/index.js';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ultrst-armada/kloks",
3
- "version": "1.22.1",
3
+ "version": "1.23.0",
4
4
  "private": false,
5
5
  "publishConfig": {
6
6
  "access": "public",
@@ -17,7 +17,9 @@
17
17
  "packages/*/dist/**",
18
18
  "packages/*/package.json",
19
19
  "packages/*/kloks.manifest.json",
20
- ".krusbl-release-attestation.json"
20
+ ".krusbl-release-attestation.json",
21
+ "packages/semantic-runtime/dist/**",
22
+ "packages/semantic-runtime/package.json"
21
23
  ],
22
24
  "exports": {
23
25
  ".": {
@@ -154,6 +156,11 @@
154
156
  "types": "./packages/aiko/dist/index.d.ts",
155
157
  "import": "./packages/aiko/dist/index.js",
156
158
  "default": "./packages/aiko/dist/index.js"
159
+ },
160
+ "./semantic-runtime": {
161
+ "types": "./packages/semantic-runtime/dist/index.d.ts",
162
+ "import": "./packages/semantic-runtime/dist/index.js",
163
+ "default": "./packages/semantic-runtime/dist/index.js"
157
164
  }
158
165
  },
159
166
  "scripts": {
@@ -0,0 +1,212 @@
1
+ type CapabilityKind = 'endpoint' | 'service' | 'fod-flow' | 'gutts' | 'knowledge' | 'agent';
2
+ type TaskStatus = 'submitted' | 'working' | 'input-required' | 'auth-required' | 'completed' | 'failed' | 'canceled' | 'rejected';
3
+ interface JsonSchema {
4
+ type?: string;
5
+ properties?: Record<string, unknown>;
6
+ required?: string[];
7
+ [key: string]: unknown;
8
+ }
9
+ interface CapabilityDescriptor {
10
+ id: string;
11
+ name: string;
12
+ description: string;
13
+ kind: CapabilityKind;
14
+ inputSchema?: JsonSchema;
15
+ outputSchema?: JsonSchema;
16
+ requirements?: RequirementTemplate[];
17
+ examples?: unknown[];
18
+ sideEffects?: 'read' | 'compute' | 'write' | 'external' | 'irreversible';
19
+ metadata?: Record<string, unknown>;
20
+ }
21
+ interface RequirementTemplate {
22
+ id: string;
23
+ semanticType: string;
24
+ description: string;
25
+ required: boolean;
26
+ sourceField?: string;
27
+ constraints?: Record<string, unknown>;
28
+ }
29
+ interface Requirement {
30
+ id: string;
31
+ semanticType: string;
32
+ description: string;
33
+ required: boolean;
34
+ sourceCapability: string;
35
+ sourceField?: string;
36
+ constraints?: Record<string, unknown>;
37
+ }
38
+ interface RuntimeContext {
39
+ applicationId: string;
40
+ sessionId: string;
41
+ userId?: string;
42
+ locale?: string;
43
+ timezone?: string;
44
+ metadata?: Record<string, unknown>;
45
+ }
46
+ interface TaskContext {
47
+ taskId: string;
48
+ parentTaskId?: string;
49
+ request: string;
50
+ intent?: string;
51
+ requirements: Requirement[];
52
+ artifacts: Artifact[];
53
+ contextId?: string;
54
+ }
55
+ interface KnowledgeContext {
56
+ sources: string[];
57
+ retrieved: unknown[];
58
+ }
59
+ interface AgentContext {
60
+ runtime: RuntimeContext;
61
+ task: TaskContext;
62
+ capabilities: CapabilityDescriptor[];
63
+ knowledge?: KnowledgeContext;
64
+ }
65
+ interface Artifact {
66
+ id: string;
67
+ type: string;
68
+ value: unknown;
69
+ producer: string;
70
+ taskId: string;
71
+ provenance?: Record<string, unknown>;
72
+ }
73
+ interface SemanticRequest {
74
+ id: string;
75
+ contextId: string;
76
+ input: string;
77
+ intent?: string;
78
+ requirements?: Requirement[];
79
+ metadata?: Record<string, unknown>;
80
+ }
81
+ interface TaskNode {
82
+ id: string;
83
+ capabilityId: string;
84
+ dependsOn: string[];
85
+ input?: unknown;
86
+ status: TaskStatus;
87
+ }
88
+ interface TaskGraph {
89
+ id: string;
90
+ requestId: string;
91
+ nodes: TaskNode[];
92
+ }
93
+ interface Task {
94
+ id: string;
95
+ status: TaskStatus;
96
+ request: string;
97
+ context: TaskContext;
98
+ result?: unknown;
99
+ error?: string;
100
+ }
101
+
102
+ declare class CapabilityRegistry {
103
+ private readonly items;
104
+ register(capability: CapabilityDescriptor): void;
105
+ upsert(capability: CapabilityDescriptor): void;
106
+ get(id: string): CapabilityDescriptor | undefined;
107
+ list(): CapabilityDescriptor[];
108
+ findBySemanticType(semanticType: string): CapabilityDescriptor[];
109
+ }
110
+
111
+ interface KnowledgeResolver {
112
+ resolve(query: string, context: TaskContext): Promise<KnowledgeContext>;
113
+ }
114
+ declare class ContextResolver {
115
+ private readonly capabilities;
116
+ private readonly knowledge?;
117
+ constructor(capabilities: CapabilityRegistry, knowledge?: KnowledgeResolver | undefined);
118
+ resolve(runtime: RuntimeContext, task: TaskContext): Promise<AgentContext>;
119
+ }
120
+
121
+ interface ResolutionResult {
122
+ resolved: boolean;
123
+ value?: unknown;
124
+ source?: string;
125
+ reason?: string;
126
+ }
127
+ interface RequirementSource {
128
+ canResolve(requirement: Requirement, context: AgentContext): Promise<boolean>;
129
+ resolve(requirement: Requirement, context: AgentContext): Promise<unknown>;
130
+ name: string;
131
+ }
132
+ declare class RequirementResolver {
133
+ private readonly registry;
134
+ private readonly sources;
135
+ constructor(registry: CapabilityRegistry, sources?: RequirementSource[]);
136
+ resolve(requirement: Requirement, context: AgentContext): Promise<ResolutionResult>;
137
+ }
138
+
139
+ interface TaskStore {
140
+ get(id: string): Task | undefined;
141
+ set(task: Task): void;
142
+ list(): Task[];
143
+ }
144
+ interface TaskEventSink {
145
+ emit(event: {
146
+ type: string;
147
+ task: Task;
148
+ }): void;
149
+ }
150
+ declare class TaskRuntime {
151
+ private readonly events?;
152
+ private readonly store;
153
+ constructor(store?: TaskStore, events?: TaskEventSink | undefined);
154
+ create(request: string, parentTaskId?: string, contextId?: `${string}-${string}-${string}-${string}-${string}`): Task;
155
+ get(id: string): Task | undefined;
156
+ transition(id: string, status: TaskStatus): Task;
157
+ addRequirement(id: string, requirement: TaskContext['requirements'][number]): Task;
158
+ addArtifact(id: string, artifact: Artifact): Task;
159
+ private mustGet;
160
+ }
161
+
162
+ declare class TaskGraphRuntime {
163
+ private readonly graphs;
164
+ create(requestId: string, nodes: Omit<TaskNode, 'status'>[]): TaskGraph;
165
+ get(id: string): TaskGraph | undefined;
166
+ ready(id: string): TaskNode[];
167
+ transition(graphId: string, nodeId: string, status: TaskNode['status']): TaskGraph;
168
+ private validate;
169
+ private mustGet;
170
+ }
171
+
172
+ interface AgentCard {
173
+ id: string;
174
+ name: string;
175
+ description: string;
176
+ role: 'application' | 'endpoint' | 'capability';
177
+ capabilities: string[];
178
+ inputModes?: string[];
179
+ outputModes?: string[];
180
+ metadata?: Record<string, unknown>;
181
+ }
182
+ declare class AgentRegistry {
183
+ private readonly agents;
184
+ register(agent: AgentCard): void;
185
+ upsert(agent: AgentCard): void;
186
+ get(id: string): AgentCard | undefined;
187
+ list(): AgentCard[];
188
+ forCapability(capability: CapabilityDescriptor): AgentCard[];
189
+ }
190
+
191
+ declare function createSemanticRequest(input: string, intent?: string): SemanticRequest;
192
+
193
+ interface AuthorizationDecision {
194
+ allowed: boolean;
195
+ reason?: string;
196
+ }
197
+ interface AuthorizationPolicy {
198
+ authorize(capability: CapabilityDescriptor, context: AgentContext): Promise<AuthorizationDecision>;
199
+ }
200
+ interface CapabilityExecutor {
201
+ execute(capability: CapabilityDescriptor, input: unknown, context: AgentContext): Promise<unknown>;
202
+ }
203
+ interface ExecutionResult {
204
+ artifact: Artifact;
205
+ }
206
+ declare class CapabilityExecutionRuntime {
207
+ private readonly policy?;
208
+ constructor(policy?: AuthorizationPolicy | undefined);
209
+ execute(capability: CapabilityDescriptor, input: unknown, context: AgentContext, executor: CapabilityExecutor): Promise<ExecutionResult>;
210
+ }
211
+
212
+ export { type AgentCard, type AgentContext, AgentRegistry, type Artifact, type AuthorizationDecision, type AuthorizationPolicy, type CapabilityDescriptor, CapabilityExecutionRuntime, type CapabilityExecutor, type CapabilityKind, CapabilityRegistry, ContextResolver, type ExecutionResult, type JsonSchema, type KnowledgeContext, type KnowledgeResolver, type Requirement, RequirementResolver, type RequirementSource, type RequirementTemplate, type ResolutionResult, type RuntimeContext, type SemanticRequest, type Task, type TaskContext, type TaskEventSink, type TaskGraph, TaskGraphRuntime, type TaskNode, TaskRuntime, type TaskStatus, type TaskStore, createSemanticRequest };
@@ -0,0 +1,205 @@
1
+ // src/registry.ts
2
+ var CapabilityRegistry = class {
3
+ items = /* @__PURE__ */ new Map();
4
+ register(capability) {
5
+ if (this.items.has(capability.id)) throw new Error(`Capability already registered: ${capability.id}`);
6
+ this.items.set(capability.id, capability);
7
+ }
8
+ upsert(capability) {
9
+ this.items.set(capability.id, capability);
10
+ }
11
+ get(id) {
12
+ return this.items.get(id);
13
+ }
14
+ list() {
15
+ return [...this.items.values()];
16
+ }
17
+ findBySemanticType(semanticType) {
18
+ return this.list().filter((c) => (c.requirements ?? []).some((r) => r.semanticType === semanticType));
19
+ }
20
+ };
21
+
22
+ // src/context.ts
23
+ var ContextResolver = class {
24
+ constructor(capabilities, knowledge) {
25
+ this.capabilities = capabilities;
26
+ this.knowledge = knowledge;
27
+ }
28
+ capabilities;
29
+ knowledge;
30
+ async resolve(runtime, task) {
31
+ const knowledge = this.knowledge ? await this.knowledge.resolve(task.request, task) : void 0;
32
+ return { runtime, task, capabilities: this.capabilities.list(), knowledge };
33
+ }
34
+ };
35
+
36
+ // src/resolution.ts
37
+ var RequirementResolver = class {
38
+ constructor(registry, sources = []) {
39
+ this.registry = registry;
40
+ this.sources = sources;
41
+ }
42
+ registry;
43
+ sources;
44
+ async resolve(requirement, context) {
45
+ for (const source of this.sources) {
46
+ if (await source.canResolve(requirement, context))
47
+ return { resolved: true, value: await source.resolve(requirement, context), source: source.name };
48
+ }
49
+ const candidates = this.registry.list().filter((c) => c.inputSchema?.properties?.[requirement.sourceField ?? ""] !== void 0);
50
+ if (candidates.length === 0)
51
+ return { resolved: false, reason: "NO_INTERNAL_RESOLUTION" };
52
+ return { resolved: false, reason: "CAPABILITY_REQUIRES_EXECUTION", source: candidates[0].id };
53
+ }
54
+ };
55
+
56
+ // src/tasks.ts
57
+ var MemoryTaskStore = class {
58
+ items = /* @__PURE__ */ new Map();
59
+ get(id) {
60
+ return this.items.get(id);
61
+ }
62
+ set(task) {
63
+ this.items.set(task.id, task);
64
+ }
65
+ list() {
66
+ return [...this.items.values()];
67
+ }
68
+ };
69
+ var TaskRuntime = class {
70
+ constructor(store = new MemoryTaskStore(), events) {
71
+ this.events = events;
72
+ this.store = store;
73
+ }
74
+ events;
75
+ store;
76
+ create(request, parentTaskId, contextId = crypto.randomUUID()) {
77
+ const id = crypto.randomUUID();
78
+ const context = { taskId: id, parentTaskId, request, requirements: [], artifacts: [], contextId };
79
+ const task = { id, status: "submitted", request, context };
80
+ this.store.set(task);
81
+ this.events?.emit({ type: "task.created", task });
82
+ return task;
83
+ }
84
+ get(id) {
85
+ return this.store.get(id);
86
+ }
87
+ transition(id, status) {
88
+ const task = this.mustGet(id);
89
+ task.status = status;
90
+ this.store.set(task);
91
+ this.events?.emit({ type: "task.status", task });
92
+ return task;
93
+ }
94
+ addRequirement(id, requirement) {
95
+ const task = this.mustGet(id);
96
+ task.context.requirements.push(requirement);
97
+ task.status = "input-required";
98
+ this.store.set(task);
99
+ this.events?.emit({ type: "task.requirement", task });
100
+ return task;
101
+ }
102
+ addArtifact(id, artifact) {
103
+ const task = this.mustGet(id);
104
+ task.context.artifacts.push(artifact);
105
+ this.store.set(task);
106
+ this.events?.emit({ type: "task.artifact", task });
107
+ return task;
108
+ }
109
+ mustGet(id) {
110
+ const task = this.store.get(id);
111
+ if (!task) throw new Error(`Unknown task: ${id}`);
112
+ return task;
113
+ }
114
+ };
115
+
116
+ // src/graph.ts
117
+ var TaskGraphRuntime = class {
118
+ graphs = /* @__PURE__ */ new Map();
119
+ create(requestId, nodes) {
120
+ const graph = { id: crypto.randomUUID(), requestId, nodes: nodes.map((n) => ({ ...n, status: "submitted" })) };
121
+ this.validate(graph);
122
+ this.graphs.set(graph.id, graph);
123
+ return graph;
124
+ }
125
+ get(id) {
126
+ return this.graphs.get(id);
127
+ }
128
+ ready(id) {
129
+ const graph = this.mustGet(id);
130
+ return graph.nodes.filter((n) => n.status === "submitted" && n.dependsOn.every((dep) => {
131
+ const node = graph.nodes.find((x) => x.id === dep);
132
+ return node?.status === "completed";
133
+ }));
134
+ }
135
+ transition(graphId, nodeId, status) {
136
+ const graph = this.mustGet(graphId);
137
+ const node = graph.nodes.find((n) => n.id === nodeId);
138
+ if (!node) throw new Error(`Unknown task graph node: ${nodeId}`);
139
+ node.status = status;
140
+ return graph;
141
+ }
142
+ validate(graph) {
143
+ const ids = new Set(graph.nodes.map((n) => n.id));
144
+ for (const node of graph.nodes) {
145
+ for (const dep of node.dependsOn) if (!ids.has(dep)) throw new Error(`Unknown dependency: ${dep}`);
146
+ }
147
+ }
148
+ mustGet(id) {
149
+ const graph = this.graphs.get(id);
150
+ if (!graph) throw new Error(`Unknown task graph: ${id}`);
151
+ return graph;
152
+ }
153
+ };
154
+
155
+ // src/agent.ts
156
+ var AgentRegistry = class {
157
+ agents = /* @__PURE__ */ new Map();
158
+ register(agent) {
159
+ if (this.agents.has(agent.id)) throw new Error(`Agent already registered: ${agent.id}`);
160
+ this.agents.set(agent.id, agent);
161
+ }
162
+ upsert(agent) {
163
+ this.agents.set(agent.id, agent);
164
+ }
165
+ get(id) {
166
+ return this.agents.get(id);
167
+ }
168
+ list() {
169
+ return [...this.agents.values()];
170
+ }
171
+ forCapability(capability) {
172
+ return this.list().filter((a) => a.capabilities.includes(capability.id));
173
+ }
174
+ };
175
+
176
+ // src/request.ts
177
+ function createSemanticRequest(input, intent) {
178
+ return { id: crypto.randomUUID(), contextId: crypto.randomUUID(), input, intent, requirements: [] };
179
+ }
180
+
181
+ // src/execution.ts
182
+ var CapabilityExecutionRuntime = class {
183
+ constructor(policy) {
184
+ this.policy = policy;
185
+ }
186
+ policy;
187
+ async execute(capability, input, context, executor) {
188
+ if (this.policy) {
189
+ const decision = await this.policy.authorize(capability, context);
190
+ if (!decision.allowed) throw new Error(decision.reason ?? "CAPABILITY_NOT_AUTHORIZED");
191
+ }
192
+ const value = await executor.execute(capability, input, context);
193
+ return { artifact: { id: crypto.randomUUID(), type: capability.outputSchema?.type ?? "application/json", value, producer: capability.id, taskId: context.task.taskId, provenance: { capabilityId: capability.id } } };
194
+ }
195
+ };
196
+ export {
197
+ AgentRegistry,
198
+ CapabilityExecutionRuntime,
199
+ CapabilityRegistry,
200
+ ContextResolver,
201
+ RequirementResolver,
202
+ TaskGraphRuntime,
203
+ TaskRuntime,
204
+ createSemanticRequest
205
+ };
@@ -0,0 +1,11 @@
1
+ {
2
+ "name":"@ultrst-armada/kloks-semantic-runtime",
3
+ "version":"0.1.0",
4
+ "type":"module",
5
+ "main":"dist/index.js",
6
+ "types":"dist/index.d.ts",
7
+ "exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},
8
+ "scripts":{"build":"tsup --config tsup.config.ts","test":"vitest run","typecheck":"tsc --noEmit -p tsconfig.json"},
9
+ "dependencies":{"zod":"^3.24.1"},
10
+ "devDependencies":{"tsup":"^8.4.0","typescript":"^5.7.3","vitest":"^3.1.0"}
11
+ }
@@ -342,6 +342,8 @@ interface SrklAccountClientOptions {
342
342
  baseUrl: string;
343
343
  userId: string;
344
344
  appId: string;
345
+ token?: string;
346
+ sessionToken?: string;
345
347
  fetchImpl?: typeof fetch;
346
348
  }
347
349
  interface SrklAccountSyncResult {
@@ -355,6 +357,8 @@ declare class SrklAccountClient {
355
357
  private readonly baseUrl;
356
358
  private readonly userId;
357
359
  private readonly appId;
360
+ private readonly token?;
361
+ private readonly sessionToken?;
358
362
  private cachedAccounts;
359
363
  constructor(options: SrklAccountClientOptions);
360
364
  sync(manifest?: SrklAccountManifest): Promise<SrklAccountSyncResult>;
@@ -2607,12 +2607,16 @@ var SrklAccountClient = class {
2607
2607
  baseUrl;
2608
2608
  userId;
2609
2609
  appId;
2610
+ token;
2611
+ sessionToken;
2610
2612
  cachedAccounts = [];
2611
2613
  constructor(options) {
2612
2614
  this.fetchImpl = options.fetchImpl || fetch;
2613
2615
  this.baseUrl = options.baseUrl.replace(/\/+$/, "");
2614
2616
  this.userId = options.userId;
2615
2617
  this.appId = options.appId;
2618
+ this.token = options.token;
2619
+ this.sessionToken = options.sessionToken;
2616
2620
  }
2617
2621
  async sync(manifest = {}) {
2618
2622
  const payload = {
@@ -2620,13 +2624,20 @@ var SrklAccountClient = class {
2620
2624
  appId: manifest.appId || this.appId,
2621
2625
  includeCredentials: manifest.includeCredentials ?? true
2622
2626
  };
2627
+ const headers = {
2628
+ "content-type": "application/json",
2629
+ "x-user-id": this.userId,
2630
+ "x-app-id": this.appId
2631
+ };
2632
+ if (this.token) {
2633
+ headers.authorization = this.token.startsWith("Bearer ") ? this.token : `Bearer ${this.token}`;
2634
+ }
2635
+ if (this.sessionToken) {
2636
+ headers["x-session-token"] = this.sessionToken;
2637
+ }
2623
2638
  const response = await this.fetchImpl(`${this.baseUrl}/api/ecosystem/accounts`, {
2624
2639
  method: "POST",
2625
- headers: {
2626
- "content-type": "application/json",
2627
- "x-user-id": this.userId,
2628
- "x-app-id": this.appId
2629
- },
2640
+ headers,
2630
2641
  body: JSON.stringify(payload)
2631
2642
  });
2632
2643
  if (!response.ok) throw new Error(`SRKL account sync failed: ${response.status}`);
@@ -16,6 +16,20 @@ import {
16
16
  useSkipoBind,
17
17
  useSkipoState
18
18
  } from "./chunk-EW4ACSZB.js";
19
+ import {
20
+ CommandApi,
21
+ GhostStore,
22
+ GraphStore
23
+ } from "./chunk-4UVGXFEM.js";
24
+ import {
25
+ BaseGraph,
26
+ BaseNode,
27
+ BaseViewWindow,
28
+ CustomGraph,
29
+ CustomNode,
30
+ CustomViewWindow,
31
+ DEFAULT_GRAPH_SETTINGS
32
+ } from "./chunk-KG6QYS26.js";
19
33
  import {
20
34
  AttractionEngine,
21
35
  GhostInferenceEngine,
@@ -31,20 +45,6 @@ import {
31
45
  WireTypeRegistry,
32
46
  initializeDefaultGraphRules
33
47
  } from "./chunk-TZOL3RN7.js";
34
- import {
35
- CommandApi,
36
- GhostStore,
37
- GraphStore
38
- } from "./chunk-4UVGXFEM.js";
39
- import {
40
- BaseGraph,
41
- BaseNode,
42
- BaseViewWindow,
43
- CustomGraph,
44
- CustomNode,
45
- CustomViewWindow,
46
- DEFAULT_GRAPH_SETTINGS
47
- } from "./chunk-KG6QYS26.js";
48
48
  import {
49
49
  AutoSolidify,
50
50
  SpatialEngine,