@lobu/runtime-device 24.5.0 → 24.7.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.
Files changed (33) hide show
  1. package/dist/component.json +1 -1
  2. package/dist/dependencies.bun.lock +32 -17
  3. package/npm-shrinkwrap.json +140 -89
  4. package/package.json +2 -1
  5. package/vendor/cli/dist/bundled-skills/lobu/SKILL.md +57 -9
  6. package/vendor/cli/dist/commands/_lib/view-bundler.js +9 -1
  7. package/vendor/cli/dist/connectors/linkedin-identity.ts +43 -0
  8. package/vendor/cli/dist/connectors/linkedin.ts +154 -3
  9. package/vendor/cli/dist/connectors/x-like-follow.ts +329 -0
  10. package/vendor/cli/dist/connectors/x.ts +709 -80
  11. package/vendor/cli/dist/internal/connector-compiler.js +3 -1
  12. package/vendor/cli/dist/runtime-components.json +4 -4
  13. package/vendor/cli/package.json +2 -1
  14. package/vendor/connector-sdk/package.json +1 -1
  15. package/vendor/connector-worker/dist/compile/index.d.ts +4 -3
  16. package/vendor/connector-worker/dist/compile/index.js +6 -3
  17. package/vendor/connector-worker/package.json +1 -1
  18. package/vendor/core/dist/contracts/tools/view-host.d.ts +7 -0
  19. package/vendor/core/dist/contracts/tools/view-host.js +28 -0
  20. package/vendor/core/dist/contracts/tools/view-runtime.d.ts +2 -4
  21. package/vendor/core/dist/contracts/tools/view-runtime.js +19 -7
  22. package/vendor/core/package.json +11 -1
  23. package/vendor/views/dist/api.d.ts +290 -0
  24. package/vendor/views/dist/api.js +714 -0
  25. package/vendor/views/dist/bridge.d.ts +157 -0
  26. package/vendor/views/dist/bridge.js +372 -0
  27. package/vendor/views/dist/components.d.ts +172 -0
  28. package/vendor/views/dist/components.js +376 -0
  29. package/vendor/views/dist/index.d.ts +13 -0
  30. package/vendor/views/dist/index.js +3 -0
  31. package/vendor/views/dist/native.d.ts +327 -0
  32. package/vendor/views/dist/native.js +57 -0
  33. package/vendor/views/package.json +53 -0
@@ -246,7 +246,9 @@ var ISOLATE_LANE_BUILD_OPTIONS = {
246
246
  platform: "node",
247
247
  conditions: ["workerd"],
248
248
  supported: { "dynamic-import": false },
249
- external: []
249
+ // This non-Node specifier is supplied by the isolate's host-backed prelude;
250
+ // unlike Node builtins, esbuild otherwise tries to resolve it as a package.
251
+ external: ["cloudflare:sockets"]
250
252
  };
251
253
  var RETAINED_SOURCE_BUILD_OPTIONS = {
252
254
  minify: true,
@@ -5,7 +5,7 @@
5
5
  "server": "dist/server.bundle.mjs",
6
6
  "embeddingsServer": "dist/embeddings-server.mjs"
7
7
  },
8
- "version": "24.5.0",
8
+ "version": "24.7.0",
9
9
  "verify": "dist/verify.mjs"
10
10
  },
11
11
  "device": {
@@ -16,7 +16,7 @@
16
16
  "connector": "node_modules/@lobu/cli/dist/commands/connector.js",
17
17
  "worker": "node_modules/@lobu/connector-worker/dist/bin.js"
18
18
  },
19
- "version": "24.5.0",
19
+ "version": "24.7.0",
20
20
  "verify": "dist/verify.mjs"
21
21
  },
22
22
  "postgres": {
@@ -24,7 +24,7 @@
24
24
  "entries": {
25
25
  "postgres": "dist/index.mjs"
26
26
  },
27
- "version": "24.5.0",
27
+ "version": "24.7.0",
28
28
  "verify": "dist/verify.mjs"
29
29
  },
30
30
  "embeddings": {
@@ -32,7 +32,7 @@
32
32
  "entries": {
33
33
  "embeddings": "dist/embeddings.js"
34
34
  },
35
- "version": "24.5.0",
35
+ "version": "24.7.0",
36
36
  "verify": "dist/verify.mjs"
37
37
  }
38
38
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lobu/cli",
3
- "version": "24.5.0",
3
+ "version": "24.7.0",
4
4
  "description": "CLI for deploying and managing AI agents on Lobu",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -34,6 +34,7 @@
34
34
  "@inquirer/prompts": "^7.10.1",
35
35
  "@lobu/connector-sdk": "file:../connector-sdk",
36
36
  "@lobu/core": "file:../core",
37
+ "@lobu/views": "file:../views",
37
38
  "@sinclair/typebox": "^0.34.41",
38
39
  "chalk": "^5.3.0",
39
40
  "commander": "^14.0.1",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lobu/connector-sdk",
3
- "version": "24.5.0",
3
+ "version": "24.7.0",
4
4
  "description": "Lobu memory SDK — build pluggable connectors for Lobu memory",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -54,8 +54,9 @@ export declare function normalizeSdkSpecifier(specifier: string): string;
54
54
  /**
55
55
  * esbuild options for code that runs inside a V8 isolate: the gateway's script
56
56
  * sandbox (`packages/server/src/sandbox/run-script.ts`, via the server's
57
- * `compiler-core`) and the connector isolate lane. `external: []` inlines every
58
- * import because an isolate has no module resolver, and `platform: 'node'`
57
+ * `compiler-core`) and the connector isolate lane. Packages are inlined because
58
+ * an isolate has no module resolver; only the provided socket shim is external.
59
+ * `platform: 'node'`
59
60
  * leaves Node builtins as bare `require()` calls that throw at load — the
60
61
  * fail-closed signal `findIsolateIneligibleBuiltins` and the lane tests key
61
62
  * on. One constant so the runtime and the tests that classify bundles can
@@ -69,7 +70,7 @@ export declare const ISOLATE_LANE_BUILD_OPTIONS: {
69
70
  readonly supported: {
70
71
  readonly 'dynamic-import': false;
71
72
  };
72
- readonly external: [];
73
+ readonly external: ["cloudflare:sockets"];
73
74
  };
74
75
  export interface NpmSpecifierPluginOptions {
75
76
  /**
@@ -88,8 +88,9 @@ export function normalizeSdkSpecifier(specifier) {
88
88
  /**
89
89
  * esbuild options for code that runs inside a V8 isolate: the gateway's script
90
90
  * sandbox (`packages/server/src/sandbox/run-script.ts`, via the server's
91
- * `compiler-core`) and the connector isolate lane. `external: []` inlines every
92
- * import because an isolate has no module resolver, and `platform: 'node'`
91
+ * `compiler-core`) and the connector isolate lane. Packages are inlined because
92
+ * an isolate has no module resolver; only the provided socket shim is external.
93
+ * `platform: 'node'`
93
94
  * leaves Node builtins as bare `require()` calls that throw at load — the
94
95
  * fail-closed signal `findIsolateIneligibleBuiltins` and the lane tests key
95
96
  * on. One constant so the runtime and the tests that classify bundles can
@@ -101,7 +102,9 @@ export const ISOLATE_LANE_BUILD_OPTIONS = {
101
102
  platform: 'node',
102
103
  conditions: ['workerd'],
103
104
  supported: { 'dynamic-import': false },
104
- external: [],
105
+ // This non-Node specifier is supplied by the isolate's host-backed prelude;
106
+ // unlike Node builtins, esbuild otherwise tries to resolve it as a package.
107
+ external: ['cloudflare:sockets'],
105
108
  };
106
109
  /**
107
110
  * Retained artifacts travel with their source, so they must be portable:
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lobu/connector-worker",
3
- "version": "24.5.0",
3
+ "version": "24.7.0",
4
4
  "description": "Self-hosted worker for Lobu memory — connectors and embedding generation",
5
5
  "type": "module",
6
6
  "bin": {
@@ -0,0 +1,7 @@
1
+ /** Browser bridge routing hints, never authority. */
2
+ export declare const VIEW_WORKSPACE_META_KEY = "lobu/view-workspace";
3
+ export declare const VIEW_OPEN_RECORD_METHOD = "lobu/open-record";
4
+ /** A mixed read/write tool is admitted only for these fixed read actions.
5
+ * The server still applies the visiting user's authorization and org scope. */
6
+ export declare function isViewRead(tool: string, args: Record<string, unknown> | undefined): boolean;
7
+ //# sourceMappingURL=view-host.d.ts.map
@@ -0,0 +1,28 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.VIEW_OPEN_RECORD_METHOD = exports.VIEW_WORKSPACE_META_KEY = void 0;
4
+ exports.isViewRead = isViewRead;
5
+ /** Browser bridge routing hints, never authority. */
6
+ exports.VIEW_WORKSPACE_META_KEY = "lobu/view-workspace";
7
+ exports.VIEW_OPEN_RECORD_METHOD = "lobu/open-record";
8
+ /** A mixed read/write tool is admitted only for these fixed read actions.
9
+ * The server still applies the visiting user's authorization and org scope. */
10
+ function isViewRead(tool, args) {
11
+ if (tool === "manage_entity") {
12
+ return (args?.action === "list" ||
13
+ args?.action === "get" ||
14
+ args?.action === "list_links");
15
+ }
16
+ if (tool === "manage_automations")
17
+ return args?.action === "list";
18
+ if (tool === "manage_agents")
19
+ return args?.action === "get";
20
+ if (tool === "manage_connections")
21
+ return args?.action === "list";
22
+ if (tool === "manage_catalog")
23
+ return args?.action === "list_installed";
24
+ return (tool === "manage_entity_schema" &&
25
+ args?.schema_type === "entity_type" &&
26
+ (args.action === "list" || args.action === "get"));
27
+ }
28
+ //# sourceMappingURL=view-host.js.map
@@ -14,8 +14,7 @@
14
14
  */
15
15
  /** Global the shell's runtime script assigns and every view bundle reads. */
16
16
  export declare const VIEW_RUNTIME_GLOBAL = "__lobuViews";
17
- /** Per-call workspace selected by an MCP view. A routing hint, never authority. */
18
- export declare const VIEW_WORKSPACE_META_KEY = "lobu/view-workspace";
17
+ export { VIEW_WORKSPACE_META_KEY } from "./view-host";
19
18
  /** Module specifiers a view imports from the shell runtime. */
20
19
  export declare const VIEW_RUNTIME_MODULES: readonly string[];
21
20
  /** Packages behind {@link VIEW_RUNTIME_MODULES}. A view whose retained
@@ -68,9 +67,8 @@ interface RuntimePluginBuild {
68
67
  * the runtime global, so the bundle carries none of the runtime. Structurally
69
68
  * typed: core does not depend on esbuild.
70
69
  */
71
- export declare function viewRuntimePlugin(): {
70
+ export declare function viewRuntimePlugin(exportNames?: Readonly<Record<string, readonly string[]>>): {
72
71
  name: string;
73
72
  setup(build: RuntimePluginBuild): void;
74
73
  };
75
- export {};
76
74
  //# sourceMappingURL=view-runtime.d.ts.map
@@ -20,8 +20,8 @@ exports.viewRuntimeEntry = viewRuntimeEntry;
20
20
  exports.viewRuntimePlugin = viewRuntimePlugin;
21
21
  /** Global the shell's runtime script assigns and every view bundle reads. */
22
22
  exports.VIEW_RUNTIME_GLOBAL = "__lobuViews";
23
- /** Per-call workspace selected by an MCP view. A routing hint, never authority. */
24
- exports.VIEW_WORKSPACE_META_KEY = "lobu/view-workspace";
23
+ var view_host_1 = require("./view-host");
24
+ Object.defineProperty(exports, "VIEW_WORKSPACE_META_KEY", { enumerable: true, get: function () { return view_host_1.VIEW_WORKSPACE_META_KEY; } });
25
25
  /** Module specifiers a view imports from the shell runtime. */
26
26
  exports.VIEW_RUNTIME_MODULES = [
27
27
  "react",
@@ -71,17 +71,29 @@ exports.VIEW_BUILD_OPTIONS = {
71
71
  * the runtime global, so the bundle carries none of the runtime. Structurally
72
72
  * typed: core does not depend on esbuild.
73
73
  */
74
- function viewRuntimePlugin() {
74
+ function viewRuntimePlugin(exportNames = {}) {
75
75
  return {
76
76
  name: "lobu-view-runtime",
77
77
  setup(build) {
78
78
  build.onResolve({ filter: /.*/ }, (args) => exports.VIEW_RUNTIME_MODULES.includes(args.path)
79
79
  ? { path: args.path, namespace: RUNTIME_NAMESPACE }
80
80
  : undefined);
81
- build.onLoad({ filter: /.*/, namespace: RUNTIME_NAMESPACE }, (args) => ({
82
- contents: `module.exports = globalThis[${JSON.stringify(exports.VIEW_RUNTIME_GLOBAL)}][${JSON.stringify(args.path)}];`,
83
- loader: "js",
84
- }));
81
+ build.onLoad({ filter: /.*/, namespace: RUNTIME_NAMESPACE }, (args) => {
82
+ const reference = `globalThis[${JSON.stringify(exports.VIEW_RUNTIME_GLOBAL)}][${JSON.stringify(args.path)}]`;
83
+ const names = exportNames[args.path];
84
+ return {
85
+ // Explicit trusted runtime exports let the compiler reject misspelled
86
+ // components, instead of installing a bundle that renders undefined.
87
+ contents: names
88
+ ? `const runtime = ${reference};\n${names
89
+ .map((name) => name === "default"
90
+ ? "export default runtime.default;"
91
+ : `export const ${name} = runtime[${JSON.stringify(name)}];`)
92
+ .join("\n")}`
93
+ : `module.exports = ${reference};`,
94
+ loader: "js",
95
+ };
96
+ });
85
97
  },
86
98
  };
87
99
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lobu/core",
3
- "version": "24.5.0",
3
+ "version": "24.7.0",
4
4
  "license": "Apache-2.0",
5
5
  "description": "Core types and utilities for Lobu agent platform",
6
6
  "repository": {
@@ -236,6 +236,16 @@
236
236
  "import": "./dist/contracts/tools/view-definition.js",
237
237
  "require": "./dist/contracts/tools/view-definition.js"
238
238
  },
239
+ "./contracts/tools/pagination": {
240
+ "types": "./dist/contracts/tools/pagination.d.ts",
241
+ "import": "./dist/contracts/tools/pagination.js",
242
+ "require": "./dist/contracts/tools/pagination.js"
243
+ },
244
+ "./contracts/tools/view-host": {
245
+ "types": "./dist/contracts/tools/view-host.d.ts",
246
+ "import": "./dist/contracts/tools/view-host.js",
247
+ "require": "./dist/contracts/tools/view-host.js"
248
+ },
239
249
  "./contracts/tools/view-runtime": {
240
250
  "types": "./dist/contracts/tools/view-runtime.d.ts",
241
251
  "import": "./dist/contracts/tools/view-runtime.js",
@@ -0,0 +1,290 @@
1
+ /**
2
+ * `@lobu/views` authoring surface (brief §1.4): `defineView`, `useParams`,
3
+ * `useScope`, `useQuery`, `useAction`, `sql`, plus the `mountView` entry the
4
+ * compiled bundle calls once. Thin layer over the hand-written `ViewBridge` —
5
+ * nothing here talks to the API directly; every read and action goes through
6
+ * the host as `tools/call`, every param change through
7
+ * `ui/update-model-context`.
8
+ *
9
+ * Contract with the host (our web host, Claude, any MCP Apps host):
10
+ * - `ui/notifications/tool-input` `arguments` = `{ scope, params }`
11
+ * (in Claude these are the `open_view` tool arguments).
12
+ * - reads: `query_sql`, `query_sdk`, and tools the registry marks
13
+ * `readOnlyHint` (`read_knowledge`, `get_automation`, `query_metric`, …);
14
+ * actions: `invoke_view_action`. The web host refuses every other tool, so
15
+ * mixed read/write tools require an explicitly admitted read action.
16
+ * Use structured `tool()` arguments for entity and schema reads.
17
+ * - `setParams` → `ui/update-model-context` `{ structuredContent: { view,
18
+ * params } }`; the web host mirrors it into the address bar. Hosts without
19
+ * that capability keep params local to the frame.
20
+ *
21
+ * Read budget: reads run on a user-facing path, when the host is ready and
22
+ * the query changes, `refetch()` is called, or a live query receives a host
23
+ * data-change notification.
24
+ * `query_sql` runs in a read-only, org-scoped transaction with a 5 second
25
+ * statement timeout and returns at most 500 rows; `useQuery` reports a hit as
26
+ * `errorCode: "UPSTREAM_TIMEOUT"` or `truncated: true`, so render those
27
+ * states instead of an empty or partial table. Each cell is bounded too
28
+ * (strings to a 4,000-code-point head plus a suffix, JSON values to 16 KiB);
29
+ * `truncatedColumns` names the columns where a returned cell was cut.
30
+ * Never aggregate history in a view: no `GROUP BY`, `DISTINCT ON`, per-row
31
+ * regexp, or leading-wildcard `LIKE` over `events` (or any other table that
32
+ * grows with history). History grows; the answer a view shows does not.
33
+ *
34
+ * For "latest state" views, compute state at write time. One event-based
35
+ * pattern is an Automation bound to the entity declaring a keyed event output
36
+ * (`outputs: { status: { event: "account_status", key: ["account"] } }`), so
37
+ * each emitted update supersedes the previous event with the same output
38
+ * identity. The view reads current events with `read_knowledge`
39
+ * (registry-marked `readOnlyHint`, so the host lets a view call it), which
40
+ * skips superseded rows:
41
+ *
42
+ * ```tsx
43
+ * const { entity } = useScope();
44
+ * const status = useQuery<{ content: Array<{ title: string | null;
45
+ * metadata: Record<string, unknown> }> }>(
46
+ * typeof entity === "number"
47
+ * ? tool("read_knowledge", { entity_id: entity,
48
+ * semantic_type: "account_status", sort_by: "date", limit: 1 })
49
+ * : null
50
+ * );
51
+ * const current = status.data?.content[0];
52
+ * ```
53
+ */
54
+ import type { CollectionSelection } from "@lobu/core/contracts/tools/collection-selection";
55
+ import type { EntityGetInput } from "@lobu/core/contracts/tools/manage-entity";
56
+ import type { ViewAttachment } from "@lobu/core/contracts/tools/manage-views";
57
+ import { type ReactNode } from "react";
58
+ import { type ToolResult, ViewBridge } from "./bridge.js";
59
+ export type ParamValue = string | number | boolean;
60
+ export type Params = Record<string, ParamValue>;
61
+ /**
62
+ * What the view is rendering. `type` on a type page, `entity` (plus its
63
+ * `type`) on a record page, `event` on an event's page, nothing on the Data hub.
64
+ *
65
+ * `event` is the resolved stored version supplied by the host. New actions
66
+ * reject a superseded version; reopening resolves the permalink again.
67
+ * There is no event hook: read it with the same exact-id read the event page
68
+ * renders. Select the supplied version from the returned lineage so the
69
+ * displayed content and action subject stay aligned:
70
+ *
71
+ * ```tsx
72
+ * export const view = defineView({
73
+ * key: "deal-won",
74
+ * attach: [{ event: "deal.won", type: "deal" }],
75
+ * });
76
+ *
77
+ * export default function DealWon() {
78
+ * const { event } = useScope();
79
+ * const read = useQuery<{ content: Array<{ id: number;
80
+ * title: string | null; metadata: Record<string, unknown> }> }>(
81
+ * event === undefined ? null : tool("read_knowledge", { content_ids: [event] })
82
+ * );
83
+ * const subject = read.data?.content.find((row) => row.id === event);
84
+ * return <h1>{subject?.title}</h1>;
85
+ * }
86
+ * ```
87
+ */
88
+ export interface Scope {
89
+ type?: string;
90
+ entity?: number | string;
91
+ event?: number;
92
+ /** Shared collection selection; absent on record, event and workspace pages.
93
+ * Pass search/filters/segment to entities.list alongside entity_type: type.
94
+ * Host selection does not replace view-specific sort/layout params. */
95
+ collection?: CollectionSelection;
96
+ }
97
+ export interface ParamDef {
98
+ type: "string" | "number" | "boolean";
99
+ default?: ParamValue;
100
+ /** Offer this param in the host's filter bar: a set value shows as a chip
101
+ * above the view, and picking one updates the param. Options make it a
102
+ * pick list; without them the host asks for a value of the param's type. */
103
+ filter?: {
104
+ label: string;
105
+ options?: Array<{
106
+ value: ParamValue;
107
+ label: string;
108
+ }>;
109
+ };
110
+ }
111
+ /**
112
+ * Where a view appears: one page per entry.
113
+ *
114
+ * - `{ record: "deal" }` — a card on every deal's page, above its activity;
115
+ * `{ record: "deal", id: 7 }` pins it to one record. The card renders
116
+ * `inline`; "See all" (`requestDisplayMode("fullscreen")`) or the card's
117
+ * Open shows the same view fullscreen in the peek.
118
+ * - `{ collection: "deal", when? }` — a tab on the deal list page. `when`
119
+ * equalities must all be present in scope.collection.filters; they control
120
+ * discoverability, never authorization.
121
+ * - `{ workspace: true }` — a tab on the Data hub.
122
+ * - `{ event: "deal.won", type? }` — one event's page, optionally only when
123
+ * the event links an entity of `type`.
124
+ */
125
+ export type Attachment = ViewAttachment;
126
+ /** How the host is showing the view: a card in a page (`inline`) or the
127
+ * view's own surface (`fullscreen`: the peek, a full page, a tab). */
128
+ export type DisplayMode = "inline" | "fullscreen";
129
+ /** The space the host gives the frame. Width is fixed or capped; an inline
130
+ * card's `maxHeight` is the height budget past which the host clips. */
131
+ export interface Container {
132
+ width?: number;
133
+ maxWidth?: number;
134
+ height?: number;
135
+ maxHeight?: number;
136
+ }
137
+ export interface ViewDefinition {
138
+ /** View key: the single namespace of keys (no `custom:` prefix). Required —
139
+ * it is the identity `invoke_view_action` and the shell route key on. */
140
+ key: string;
141
+ /** Display name; defaults to the key when the view is saved. */
142
+ name?: string;
143
+ description?: string;
144
+ /** Where the view appears. The attach line lives in the module; there are
145
+ * no attach/detach verbs. */
146
+ attach: Attachment[];
147
+ params?: Record<string, ParamDef>;
148
+ actions?: Record<string, {
149
+ emits: string;
150
+ }>;
151
+ }
152
+ export declare function defineView(def: ViewDefinition): ViewDefinition;
153
+ export declare function useParams(): readonly [
154
+ Params,
155
+ (patch: Partial<Params>) => void
156
+ ];
157
+ export declare function useScope(): Scope;
158
+ export declare function useHost(): {
159
+ connected: boolean;
160
+ ready: boolean;
161
+ theme: "light" | "dark";
162
+ /**
163
+ * Ask the host to open `url`. A relative URL (`"deal/acme-renewal"`, a
164
+ * record's `<type>/<slug>`) resolves against the workspace root, so the same
165
+ * link works on every page and in every host; a full URL opens outside the
166
+ * app. The frame is sandboxed, so this is the only way a view navigates;
167
+ * rejects when the host declines.
168
+ */
169
+ openLink: (url: string) => Promise<void>;
170
+ openRecord: (record: EntityGetInput, options?: {
171
+ mode?: "peek" | "page";
172
+ }) => Promise<{
173
+ mode: "peek" | "page";
174
+ }>;
175
+ /** `inline` as a card on a page, `fullscreen` as the view's own surface.
176
+ * Render a summary inline and the full view fullscreen. */
177
+ displayMode: DisplayMode;
178
+ container: Container;
179
+ /** Ask the host for another mode ("See all" → `"fullscreen"`). Resolves with
180
+ * the mode the host set, which stays the current one when it declines. */
181
+ requestDisplayMode: (mode: DisplayMode) => Promise<DisplayMode>;
182
+ };
183
+ /** The workspace root relative links resolve against: the shell's
184
+ * `lobu-workspace` meta, absent outside a server-rendered shell. */
185
+ export declare function resolveViewHref(href: string): string;
186
+ /**
187
+ * Tagged template: scalar values are rendered as escaped SQL literals,
188
+ * never spliced raw. Numbers must be finite, booleans map to true/false,
189
+ * null/undefined become NULL, strings are single-quote escaped; anything
190
+ * else (objects, arrays) throws rather than stringifying a blob into the
191
+ * query. `query_sql` takes no bind parameters, so the guest escapes and the
192
+ * server validates tables — server-side binding stays a one-paragraph
193
+ * proposal until a use case needs it.
194
+ */
195
+ export interface SqlQuery {
196
+ kind: "sql";
197
+ text: string;
198
+ }
199
+ export declare function sql(strings: TemplateStringsArray, ...values: unknown[]): SqlQuery;
200
+ export declare function escapeLiteral(value: unknown): string;
201
+ /** Direct tool read, for a tool the registry marks `readOnlyHint`
202
+ * (`read_knowledge`, `get_automation`, …). The web host refuses mixed
203
+ * read/write tools require an explicitly admitted read action. */
204
+ export interface ToolQuery {
205
+ kind: "tool";
206
+ name: string;
207
+ args: Record<string, unknown>;
208
+ }
209
+ export declare function tool(name: string, args?: Record<string, unknown>): ToolQuery;
210
+ /**
211
+ * Read one `useQuery` result. A failed read is an error, never an empty
212
+ * result: `query_sql` answers a rejected statement (unknown table, bad column)
213
+ * with a normal result carrying `error` beside `rows: []`, and `query_sdk`
214
+ * reports a thrown script as `success: false` — both would otherwise render as
215
+ * "no rows". The server's typed code rides along as `errorCode`, and a capped
216
+ * result (`query_sql`'s `has_more`, `query_sdk`'s `return_truncated`) is
217
+ * flagged `truncated` instead of passing as the whole answer, and a
218
+ * `query_sql` cell bounded by its size limits is named in `truncatedColumns`.
219
+ */
220
+ export declare function queryResult<T>(kind: "sql" | "sdk" | "tool", result: ToolResult): Pick<QueryState<T>, "data" | "error" | "errorCode" | "truncated" | "truncatedColumns">;
221
+ export interface QueryState<T> {
222
+ data: T | null;
223
+ error: string | null;
224
+ /** The server's typed code for a failed read, e.g. `UPSTREAM_TIMEOUT` when
225
+ * the statement ran past `query_sql`'s 5 second timeout. Branch on this,
226
+ * never on `error` text. Null on success or when the host gave no code. */
227
+ errorCode: string | null;
228
+ /** True when the server capped the answer: `query_sql` returns at most 500
229
+ * rows (fewer past its response-size ceiling) and `query_sdk` drops an
230
+ * oversized return value. `data` is then not the whole result. */
231
+ truncated: boolean;
232
+ /** `query_sql` columns where a returned cell was bounded: a string cut to
233
+ * its first 4,000 Unicode code points plus "… [truncated]", or a JSON value
234
+ * over 16 KiB replaced by `{ _truncated: true, bytes }` (attachments become
235
+ * null with attachments_truncated). Show those cells as too large, or select
236
+ * smaller elements or fields, e.g. `jsonb_array_elements(metadata->'items')`.
237
+ * Paginate as needed; each returned cell is still subject to these limits. */
238
+ truncatedColumns: string[];
239
+ loading: boolean;
240
+ refetch: () => void;
241
+ }
242
+ export interface QueryOptions {
243
+ /** Re-read in the background whenever workspace data changes (default
244
+ * true). Pass false for a read that reaches a remote source, such as a
245
+ * `feeds.readMany` search: it then runs once per query and again only on
246
+ * `refetch()`. */
247
+ live?: boolean;
248
+ }
249
+ /**
250
+ * Run a read through the host. `sql\`…\`` → `query_sql`; a string →
251
+ * `query_sdk` script; `tool(name, args)` → that tool; `null` skips. The first
252
+ * fetch waits for the host's first `tool-input`: reads before it run against
253
+ * defaults and double-fetch when the real scope lands.
254
+ */
255
+ export declare function useQuery<T = unknown>(query: SqlQuery | ToolQuery | string | null, options?: QueryOptions): QueryState<T>;
256
+ export interface ActionResult {
257
+ ok: boolean;
258
+ error: string | null;
259
+ result: unknown;
260
+ /** Retry the same submission after a failed acknowledgement. A new call to
261
+ * useAction's function is a new intent, even when its value is identical. */
262
+ retry: (() => Promise<ActionResult>) | null;
263
+ }
264
+ /** Mint one id for a deliberate submission, retained by its retry closure. */
265
+ export declare function mintInteractionId(): string;
266
+ /** Submit a declared action. Failed acknowledgements expose an explicit retry
267
+ * that keeps the original value, event subject and interaction id. */
268
+ export declare function useAction(name: string): (value?: Record<string, unknown>) => Promise<ActionResult>;
269
+ export declare function defaultsFor(def: ViewDefinition): Params;
270
+ export declare function coerceParams(def: ViewDefinition, raw: unknown): Params;
271
+ export declare function coerceScope(raw: unknown): Scope;
272
+ /**
273
+ * Host bridge provider: seeds scope/params from the first tool-input,
274
+ * exposes reads/actions over tools/call, mirrors params through
275
+ * update-model-context. The server bootstrap renders this around the view's
276
+ * default export; `mountView` does the same for CLI-bundled entries.
277
+ */
278
+ export declare function Provider({ def, bridge, children, }: {
279
+ def: ViewDefinition;
280
+ bridge?: ViewBridge;
281
+ children: ReactNode;
282
+ }): import("react/jsx-runtime").JSX.Element;
283
+ export interface MountOptions {
284
+ /** Test seam: drive the view against a fake parent instead of `window.parent`. */
285
+ bridge?: ViewBridge;
286
+ }
287
+ /** Entry point the compiled bundle calls once. Mounts the component into
288
+ * `#root` and connects to the host. */
289
+ export declare function mountView(def: ViewDefinition, Component: () => ReactNode, opts?: MountOptions): void;
290
+ //# sourceMappingURL=api.d.ts.map