skillar 0.2.1 → 0.3.1

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 (111) hide show
  1. package/NOTICE +280 -0
  2. package/README.md +37 -5
  3. package/dist/analysis/finding.js +8 -190
  4. package/dist/analysis/kernel.js +896 -0
  5. package/dist/analysis/tree.js +7 -154
  6. package/dist/analysis/usage.js +9 -394
  7. package/dist/api/flows.js +42 -212
  8. package/dist/api/report-kernel.js +1063 -0
  9. package/dist/api/routes.js +12 -2
  10. package/dist/catalog/fields.js +138 -146
  11. package/dist/catalog/watcher.js +7 -2
  12. package/dist/cli/init.js +45 -0
  13. package/dist/cli/main.js +76 -3
  14. package/dist/cli/private-skills.js +122 -0
  15. package/dist/cli/serve.js +15 -1
  16. package/dist/cli/sync.js +124 -0
  17. package/dist/dashboard/NOTICE +280 -0
  18. package/dist/dashboard/assets/app.js +737 -275
  19. package/dist/dashboard/assets/astryx-reset.css +407 -0
  20. package/dist/dashboard/assets/astryx.css +1077 -0
  21. package/dist/dashboard/assets/charts.css +54 -0
  22. package/dist/dashboard/assets/chunk-TPGDA2J4.js +1 -0
  23. package/dist/dashboard/assets/chunk-YLWHVDMP.js +36 -0
  24. package/dist/dashboard/assets/controls.css +207 -0
  25. package/dist/dashboard/assets/overlays.css +132 -0
  26. package/dist/dashboard/assets/p1.css +135 -0
  27. package/dist/dashboard/assets/shell.css +71 -0
  28. package/dist/dashboard/assets/skillar-theme.css +692 -0
  29. package/dist/dashboard/assets/styles.css +224 -121
  30. package/dist/dashboard/assets/tokens.css +278 -0
  31. package/dist/dashboard/assets/widgets.css +83 -0
  32. package/dist/dashboard/index.html +11 -2
  33. package/dist/dashboard/viewers/viewers.css +61 -0
  34. package/dist/ingest/attribution.js +5 -1
  35. package/dist/ingest/pipeline.js +2 -0
  36. package/dist/ingest/request-recorder.js +39 -0
  37. package/dist/mcp/dispatch.js +2 -2
  38. package/dist/mcp/http.js +43 -3
  39. package/dist/mcp/skills-extension.js +42 -15
  40. package/dist/mcp/stdio-proxy.js +24 -3
  41. package/dist/mcp/tools.js +38 -24
  42. package/dist/packs/claude-code.js +22 -11
  43. package/dist/packs/cursor.js +9 -4
  44. package/dist/packs/gemini.js +9 -4
  45. package/dist/packs/json-config.js +41 -0
  46. package/dist/packs/omo.js +15 -6
  47. package/dist/request-status.js +81 -0
  48. package/dist/search/fts.js +93 -58
  49. package/dist/search/fusion.js +49 -47
  50. package/dist/search/guidance.js +18 -6
  51. package/dist/search/index.js +291 -70
  52. package/dist/search/lexical.js +71 -63
  53. package/dist/server.js +12 -0
  54. package/dist/skills/apply.js +130 -0
  55. package/dist/skills/capture.js +54 -0
  56. package/dist/skills/cloud-plan.js +57 -0
  57. package/dist/skills/cloud.js +81 -0
  58. package/dist/skills/fs.js +133 -0
  59. package/dist/skills/package.js +734 -0
  60. package/dist/skills/plan.js +83 -0
  61. package/dist/skills/receipt.js +44 -0
  62. package/dist/skills/rollback.js +119 -0
  63. package/dist/skills/transfer.js +51 -0
  64. package/dist/store/db.js +7 -1
  65. package/dist/store/execution.js +2 -34
  66. package/dist/store/export.js +25 -4
  67. package/dist/store/migrations/007_sync.sql +49 -0
  68. package/dist/store/migrations/008_connector_commands.sql +12 -0
  69. package/dist/store/queries.js +33 -7
  70. package/dist/store/writes.js +38 -5
  71. package/dist/sync/cloud-blobs.js +175 -0
  72. package/dist/sync/cloud-commands.js +101 -0
  73. package/dist/sync/cloud-connection.js +105 -0
  74. package/dist/sync/cloud-delivery.js +114 -0
  75. package/dist/sync/cloud-documents.js +103 -0
  76. package/dist/sync/cloud-export.js +67 -0
  77. package/dist/sync/cloud-http.js +150 -0
  78. package/dist/sync/cloud-jobs.js +94 -0
  79. package/dist/sync/cloud-pending.js +143 -0
  80. package/dist/sync/cloud-prepare.js +101 -0
  81. package/dist/sync/cloud-restore.js +136 -0
  82. package/dist/sync/cloud-rollback.js +24 -0
  83. package/dist/sync/cloud-runner.js +86 -0
  84. package/dist/sync/cloud-runtime.js +293 -0
  85. package/dist/sync/cloud-schema.js +32 -0
  86. package/dist/sync/cloud-stage.js +112 -0
  87. package/dist/sync/cloud-wire.js +693 -0
  88. package/dist/sync/cloud-worker.js +57 -0
  89. package/dist/sync/cloud.js +157 -0
  90. package/dist/sync/command-apply.js +140 -0
  91. package/dist/sync/command-control.js +25 -0
  92. package/dist/sync/command-wire.js +437 -0
  93. package/dist/sync/consent.js +130 -0
  94. package/dist/sync/journal.js +43 -0
  95. package/dist/sync/outbox.js +134 -0
  96. package/dist/sync/restore-rows.js +125 -0
  97. package/dist/sync/restore.js +174 -0
  98. package/dist/sync/snapshot.js +78 -0
  99. package/dist/sync/spool-request.js +103 -0
  100. package/dist/sync/tables.js +27 -0
  101. package/dist/sync/triggers.js +34 -0
  102. package/dist/workflow/compare.js +3 -43
  103. package/docs/cloud-sync.md +94 -0
  104. package/docs/private-skills.md +75 -0
  105. package/docs/sync-p4.md +102 -0
  106. package/docs/sync-restore.md +167 -0
  107. package/package.json +18 -5
  108. package/src/store/migrations/007_sync.sql +49 -0
  109. package/src/store/migrations/008_connector_commands.sql +12 -0
  110. package/dist/dashboard/assets/chunk-5DFWNJC2.js +0 -1
  111. package/dist/dashboard/assets/chunk-S6B2HJQA.js +0 -17
@@ -0,0 +1,83 @@
1
+ import { dirname, isAbsolute, join, resolve } from "node:path";
2
+ import { z } from "zod";
3
+ import { PRIVATE_SKILL_MAX_BYTES, PRIVATE_SKILL_MAX_REQUEST_BYTES, PRIVATE_SKILL_MAX_RESOURCE_BYTES, PRIVATE_SKILL_MAX_RESOURCES, privateSkillExportSchema, privateSkillPathSchema, verifyPrivateSkillPackage, } from "./package.js";
4
+ import { ancestors, checkDirectories, directoryIdentity, identitySchema, inside, readJson, readRegular, sameState, SkillApplyError, stateSchema, writeExclusive, } from "./fs.js";
5
+ export const MAX_PLAN_BYTES = PRIVATE_SKILL_MAX_REQUEST_BYTES + 1024 * 1024;
6
+ export const directorySchema = z.strictObject({
7
+ path: z.string().max(4096), identity: identitySchema.nullable(),
8
+ }).readonly();
9
+ export const planSchema = z.strictObject({
10
+ schemaVersion: z.literal(1), root: z.string().min(1).max(4096),
11
+ allowOverwrite: z.boolean(), exported: privateSkillExportSchema,
12
+ directories: z.array(directorySchema).min(1).max(1024).readonly(),
13
+ files: z.array(z.strictObject({
14
+ path: privateSkillPathSchema, before: stateSchema.nullable(),
15
+ }).readonly()).min(1).max(PRIVATE_SKILL_MAX_RESOURCES).readonly(),
16
+ }).readonly();
17
+ function plannedDirectories(root, paths) {
18
+ return [...new Set([...ancestors(root), ...paths.flatMap(path => ancestors(dirname(join(root, path))))])]
19
+ .sort((a, b) => a.length - b.length || a.localeCompare(b));
20
+ }
21
+ export async function verifyPlan(input) {
22
+ const plan = planSchema.parse(input);
23
+ const verified = await verifyPrivateSkillPackage(plan.exported.package);
24
+ if (plan.exported.version.digest !== verified.package.manifestDigest) {
25
+ throw new SkillApplyError("version_digest", "export version differs from package");
26
+ }
27
+ const resources = verified.package.manifest.resources;
28
+ const directories = plannedDirectories(plan.root, resources.map(resource => resource.path));
29
+ if (!isAbsolute(plan.root) || resolve(plan.root) !== plan.root ||
30
+ plan.files.length !== resources.length || directories.length !== plan.directories.length ||
31
+ directories.some((path, index) => path !== plan.directories[index]?.path) ||
32
+ plan.files.some((file, index) => file.path !== resources[index]?.path ||
33
+ (file.before !== null && (!plan.allowOverwrite || file.before.size > PRIVATE_SKILL_MAX_RESOURCE_BYTES))) ||
34
+ plan.files.reduce((sum, file) => sum + (file.before?.size ?? 0), 0) > PRIVATE_SKILL_MAX_BYTES ||
35
+ plan.directories.some(dir => inside(dir.path, plan.root) && dir.identity === null)) {
36
+ throw new SkillApplyError("invalid_plan", "membership, root, ancestors, overwrite permission or quota");
37
+ }
38
+ return plan;
39
+ }
40
+ export async function loadPlan(path) {
41
+ return verifyPlan(readJson(path, MAX_PLAN_BYTES));
42
+ }
43
+ export function checkBefore(plan, directories = plan.directories) {
44
+ checkDirectories(directories);
45
+ for (const file of plan.files) {
46
+ const current = readRegular(join(plan.root, file.path), PRIVATE_SKILL_MAX_RESOURCE_BYTES);
47
+ if (!sameState(file.before, current?.state ?? null))
48
+ throw new SkillApplyError("target_changed", file.path);
49
+ }
50
+ checkDirectories(directories);
51
+ }
52
+ export async function previewSkill(opts) {
53
+ const exported = privateSkillExportSchema.parse(readJson(opts.packagePath, PRIVATE_SKILL_MAX_REQUEST_BYTES));
54
+ await verifyPrivateSkillPackage(exported.package);
55
+ if (exported.version.digest !== exported.package.manifestDigest)
56
+ throw new SkillApplyError("version_digest", opts.packagePath);
57
+ const root = resolve(opts.destinationRoot);
58
+ const planPath = resolve(opts.planPath);
59
+ if (inside(root, planPath))
60
+ throw new SkillApplyError("plan_in_destination", planPath);
61
+ const directories = plannedDirectories(root, exported.package.manifest.resources.map(resource => resource.path))
62
+ .map(path => ({ path, identity: directoryIdentity(path) }));
63
+ if (directories.some(dir => inside(dir.path, root) && dir.identity === null)) {
64
+ throw new SkillApplyError("missing_root", root);
65
+ }
66
+ const files = exported.package.manifest.resources.map(resource => ({
67
+ path: resource.path, before: readRegular(join(root, resource.path), PRIVATE_SKILL_MAX_RESOURCE_BYTES)?.state ?? null,
68
+ }));
69
+ if (!opts.allowOverwrite && files.some(file => file.before !== null)) {
70
+ throw new SkillApplyError("overwrite_requires_permission", "preview again with --allow-overwrite");
71
+ }
72
+ const plan = await verifyPlan({ schemaVersion: 1, root, allowOverwrite: opts.allowOverwrite ?? false, exported, directories, files });
73
+ checkBefore(plan);
74
+ const text = JSON.stringify(plan);
75
+ if (Buffer.byteLength(text) > MAX_PLAN_BYTES)
76
+ throw new SkillApplyError("quota", "plan");
77
+ const parents = ancestors(dirname(planPath)).map(path => ({ path, identity: directoryIdentity(path) }));
78
+ if (parents.some(dir => dir.identity === null))
79
+ throw new SkillApplyError("missing_directory", dirname(planPath));
80
+ checkDirectories(parents);
81
+ writeExclusive(planPath, text);
82
+ return plan;
83
+ }
@@ -0,0 +1,44 @@
1
+ import { join, resolve } from "node:path";
2
+ import { z } from "zod";
3
+ import { digest, identitySchema, readJson, sameIdentity, SkillApplyError } from "./fs.js";
4
+ import { directorySchema, planSchema, verifyPlan } from "./plan.js";
5
+ import { PRIVATE_SKILL_MAX_REQUEST_BYTES, PRIVATE_SKILL_MAX_RESOURCES, privateSkillBodySchema } from "./package.js";
6
+ // A receipt embeds the plan plus bounded before-file backups.
7
+ export const MAX_RECEIPT_BYTES = 2 * PRIVATE_SKILL_MAX_REQUEST_BYTES + 2 * 1024 * 1024;
8
+ export const receiptSchema = z.strictObject({
9
+ schemaVersion: z.literal(1), runId: z.string().uuid(), plan: planSchema,
10
+ recoveryIdentity: identitySchema,
11
+ directories: z.array(directorySchema).min(1).max(1024).readonly(),
12
+ entries: z.array(z.strictObject({
13
+ beforeBody: privateSkillBodySchema.nullable(), writtenIdentity: identitySchema,
14
+ writtenMtime: z.string().regex(/^\d+$/).max(40),
15
+ }).readonly()).min(1).max(PRIVATE_SKILL_MAX_RESOURCES).readonly(),
16
+ }).readonly();
17
+ export const recoveryDirectory = (receipt) => join(receipt.plan.root, `.skillar-private-${receipt.runId}`);
18
+ export const displacedPath = (receipt, index) => join(recoveryDirectory(receipt), `displaced-${index}`);
19
+ /** A receipt is an immutable write-ahead journal, not an assertion that apply succeeded. */
20
+ export async function loadReceipt(path) {
21
+ const receipt = receiptSchema.parse(readJson(path, MAX_RECEIPT_BYTES));
22
+ await verifyPlan(receipt.plan);
23
+ if (resolve(path) !== join(recoveryDirectory(receipt), "receipt.json") ||
24
+ receipt.entries.length !== receipt.plan.files.length ||
25
+ receipt.directories.length !== receipt.plan.directories.length ||
26
+ receipt.directories.some((dir, index) => {
27
+ const planned = receipt.plan.directories[index];
28
+ return planned === undefined || dir.path !== planned.path || dir.identity === null ||
29
+ (planned.identity !== null && !sameIdentity(dir.identity, planned.identity));
30
+ }))
31
+ throw new SkillApplyError("invalid_receipt", "path, directories or membership");
32
+ for (const [index, entry] of receipt.entries.entries()) {
33
+ const file = receipt.plan.files[index];
34
+ if (file === undefined)
35
+ throw new SkillApplyError("invalid_receipt", "missing file");
36
+ const bytes = entry.beforeBody === null ? null : Buffer.from(entry.beforeBody, "base64");
37
+ if (file.before === null ? bytes !== null :
38
+ bytes === null || bytes.toString("base64") !== entry.beforeBody ||
39
+ bytes.length !== file.before.size || digest(bytes) !== file.before.digest) {
40
+ throw new SkillApplyError("invalid_receipt", file.path);
41
+ }
42
+ }
43
+ return receipt;
44
+ }
@@ -0,0 +1,119 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import { chmodSync, linkSync, renameSync } from "node:fs";
3
+ import { join } from "node:path";
4
+ import { checkDirectories, readRegular, sameIdentity, sameState, SkillApplyError, writeExclusive, } from "./fs.js";
5
+ import { PRIVATE_SKILL_MAX_RESOURCE_BYTES } from "./package.js";
6
+ import { displacedPath, loadReceipt, recoveryDirectory } from "./receipt.js";
7
+ export function checkReceiptDirectories(receipt) {
8
+ checkDirectories([...receipt.directories, {
9
+ path: recoveryDirectory(receipt), identity: receipt.recoveryIdentity,
10
+ }]);
11
+ }
12
+ /** Retain all displaced bytes. No replacement rename is used to restore a pathname. */
13
+ export function restoreReceipt(receipt, options = {}) {
14
+ const outcomes = [];
15
+ for (const [index, file] of [...receipt.plan.files.entries()].reverse()) {
16
+ const path = join(receipt.plan.root, file.path);
17
+ try {
18
+ options.hook?.({ phase: "before_rollback", index });
19
+ checkReceiptDirectories(receipt);
20
+ const entry = receipt.entries[index];
21
+ const resource = receipt.plan.exported.package.manifest.resources[index];
22
+ if (entry === undefined || resource === undefined)
23
+ throw new SkillApplyError("invalid_receipt", file.path);
24
+ const current = readRegular(path, PRIVATE_SKILL_MAX_RESOURCE_BYTES);
25
+ if ((current === null && file.before === null) ||
26
+ (current !== null && file.before !== null &&
27
+ current.state.digest === file.before.digest && current.state.mode === file.before.mode)) {
28
+ outcomes.push({ path, status: "unchanged" });
29
+ continue;
30
+ }
31
+ if (current !== null && (current.state.digest !== resource.digest ||
32
+ current.state.mode !== 0o600 || current.state.mtime !== entry.writtenMtime ||
33
+ !sameIdentity(current.state.identity, entry.writtenIdentity))) {
34
+ throw new SkillApplyError("rollback_conflict", path);
35
+ }
36
+ // An absent overwrite target is recoverable only with proof that we displaced it.
37
+ if (current === null) {
38
+ // Explicit rollback must not undo a subsequent deletion. Only the live
39
+ // apply knows a name is missing because installation has not happened.
40
+ if (!options.displacedOnly?.has(index))
41
+ throw new SkillApplyError("rollback_conflict", path);
42
+ const displaced = readRegular(displacedPath(receipt, index), PRIVATE_SKILL_MAX_RESOURCE_BYTES);
43
+ if (file.before === null || displaced === null || displaced.state.digest !== file.before.digest ||
44
+ !sameIdentity(displaced.state.identity, file.before.identity)) {
45
+ throw new SkillApplyError("rollback_conflict", path);
46
+ }
47
+ }
48
+ const restore = join(recoveryDirectory(receipt), `restore-${index}-${randomUUID()}`);
49
+ if (entry.beforeBody !== null) {
50
+ writeExclusive(restore, Buffer.from(entry.beforeBody, "base64"));
51
+ chmodSync(restore, file.before?.mode ?? 0o600);
52
+ }
53
+ options.hook?.({ phase: "before_restore", index });
54
+ checkReceiptDirectories(receipt);
55
+ if (!sameState(readRegular(path, PRIVATE_SKILL_MAX_RESOURCE_BYTES)?.state ?? null, current?.state ?? null)) {
56
+ throw new SkillApplyError("rollback_conflict", path);
57
+ }
58
+ if (current !== null) {
59
+ const retained = join(recoveryDirectory(receipt), `rollback-${index}-${randomUUID()}`);
60
+ renameSync(path, retained);
61
+ options.hook?.({ phase: "after_rollback_displace", index });
62
+ checkReceiptDirectories(receipt);
63
+ const moved = readRegular(retained, PRIVATE_SKILL_MAX_RESOURCE_BYTES);
64
+ // Rename changes ctime, so compare bytes and inode, not the old ctime.
65
+ if (moved === null || moved.state.digest !== current.state.digest ||
66
+ !sameIdentity(moved.state.identity, current.state.identity) || moved.state.mode !== current.state.mode ||
67
+ moved.state.mtime !== current.state.mtime) {
68
+ // Put back the captured edit only if the name is still vacant; otherwise retain it.
69
+ if (moved !== null)
70
+ linkSync(retained, path);
71
+ throw new SkillApplyError("rollback_conflict", `captured edit retained at ${retained}`);
72
+ }
73
+ }
74
+ checkReceiptDirectories(receipt);
75
+ if (entry.beforeBody !== null)
76
+ linkSync(restore, path);
77
+ checkReceiptDirectories(receipt);
78
+ const final = readRegular(path, PRIVATE_SKILL_MAX_RESOURCE_BYTES);
79
+ if (file.before === null ? final !== null :
80
+ final === null || final.state.digest !== file.before.digest || final.state.mode !== file.before.mode) {
81
+ throw new SkillApplyError("rollback_conflict", path);
82
+ }
83
+ outcomes.push({ path, status: entry.beforeBody === null ? "removed" : "restored" });
84
+ }
85
+ catch (error) {
86
+ if (!(error instanceof Error))
87
+ throw error;
88
+ outcomes.push({ path, status: "conflict", detail: error.message });
89
+ }
90
+ }
91
+ // Later operations may have raced edits to earlier restored targets. Report
92
+ // their final observed state, without attempting to overwrite those edits.
93
+ return outcomes.map(outcome => {
94
+ if (outcome.status === "conflict")
95
+ return outcome;
96
+ try {
97
+ checkReceiptDirectories(receipt);
98
+ const file = receipt.plan.files.find(file => join(receipt.plan.root, file.path) === outcome.path);
99
+ if (file === undefined)
100
+ throw new SkillApplyError("invalid_receipt", outcome.path);
101
+ const current = readRegular(outcome.path, PRIVATE_SKILL_MAX_RESOURCE_BYTES);
102
+ if (file.before === null ? current !== null : current === null ||
103
+ current.state.digest !== file.before.digest || current.state.mode !== file.before.mode) {
104
+ throw new SkillApplyError("rollback_conflict", outcome.path);
105
+ }
106
+ return outcome;
107
+ }
108
+ catch (error) {
109
+ if (!(error instanceof Error))
110
+ throw error;
111
+ return { path: outcome.path, status: "conflict", detail: error.message };
112
+ }
113
+ });
114
+ }
115
+ export async function rollbackSkill(path, hook) {
116
+ const receipt = await loadReceipt(path);
117
+ const outcomes = restoreReceipt(receipt, { hook });
118
+ return { status: outcomes.some(outcome => outcome.status === "conflict") ? "conflict" : "rolled_back", receipt: path, outcomes };
119
+ }
@@ -0,0 +1,51 @@
1
+ import { capturePrivateSkill } from "./capture.js";
2
+ import { privateSkillCloud } from "./cloud.js";
3
+ import { readPublicationPlan } from "./cloud-plan.js";
4
+ import { sameIdentity, SkillApplyError, writeExclusive } from "./fs.js";
5
+ import { privateSkillDetailSchema, privateSkillDigestSchema, privateSkillExportSchema, privateSkillIdSchema, verifyPrivateSkillPackage, } from "./package.js";
6
+ /** Only explicit confirmation can upload the exact reviewed, unchanged package. */
7
+ export async function pushPrivateSkill(home, planPath, acknowledgePrivateUpload, fetcher = fetch) {
8
+ if (!acknowledgePrivateUpload)
9
+ throw new SkillApplyError("private_upload_ack_required", "review and confirm the publication plan");
10
+ const plan = await readPublicationPlan(planPath);
11
+ const captured = await capturePrivateSkill(plan.sourceRoot);
12
+ if (!sameIdentity(captured.rootIdentity, plan.rootIdentity) ||
13
+ captured.package.manifestDigest !== plan.package.manifestDigest) {
14
+ throw new SkillApplyError("source_changed", plan.sourceRoot);
15
+ }
16
+ const client = await privateSkillCloud(home, true, fetcher);
17
+ if (client.identity.accountId !== plan.accountId || client.identity.generation !== plan.generation ||
18
+ client.identity.origin !== plan.origin || client.identity.instanceId !== plan.instanceId ||
19
+ client.identity.deviceId !== plan.deviceId) {
20
+ throw new SkillApplyError("connection_changed", "create a new publication preview");
21
+ }
22
+ const detail = privateSkillDetailSchema.parse(await client.request(`/${plan.skillId}/versions`, {
23
+ base: plan.base, acknowledgePrivateUpload: true, package: plan.package,
24
+ }));
25
+ if (detail.skill.skillId !== plan.skillId || detail.skill.head.digest !== plan.package.manifestDigest ||
26
+ detail.skill.head.revision !== (plan.base?.revision ?? 0) + 1) {
27
+ throw new SkillApplyError("publication_unverified", "the server did not acknowledge the reviewed head");
28
+ }
29
+ return { status: "published", skillId: plan.skillId, head: detail.skill.head };
30
+ }
31
+ /** A verified immutable export is saved privately for a separate local apply preview. */
32
+ export async function pullPrivateSkill(home, input, fetcher = fetch) {
33
+ const skillId = privateSkillIdSchema.parse(input.skillId);
34
+ const client = await privateSkillCloud(home, false, fetcher);
35
+ let digest;
36
+ if (input.digest === undefined) {
37
+ const detail = privateSkillDetailSchema.parse(await client.request(`/${skillId}`));
38
+ if (detail.skill.skillId !== skillId)
39
+ throw new SkillApplyError("identity_mismatch", "unexpected skill metadata");
40
+ digest = detail.skill.head.digest;
41
+ }
42
+ else
43
+ digest = privateSkillDigestSchema.parse(input.digest);
44
+ const exported = privateSkillExportSchema.parse(await client.request(`/${skillId}/versions/${digest}`));
45
+ await verifyPrivateSkillPackage(exported.package);
46
+ if (exported.skillId !== skillId || exported.version.digest !== digest || exported.package.manifestDigest !== digest) {
47
+ throw new SkillApplyError("export_unverified", "the returned version did not match the requested pin");
48
+ }
49
+ writeExclusive(input.outputPath, JSON.stringify(exported));
50
+ return { status: "downloaded", skillId, digest, file: input.outputPath };
51
+ }
package/dist/store/db.js CHANGED
@@ -2,7 +2,8 @@ import { mkdirSync, readFileSync } from "node:fs";
2
2
  import { dirname } from "node:path";
3
3
  import { DatabaseSync } from "node:sqlite";
4
4
  import { SkillarStartupError } from "../version.js";
5
- export const SCHEMA_VERSION = 6;
5
+ import { installJournalTriggers } from "../sync/triggers.js";
6
+ export const SCHEMA_VERSION = 8;
6
7
  /** migrations[i] upgrades user_version i -> i + 1. */
7
8
  function migrations() {
8
9
  return [
@@ -12,6 +13,8 @@ function migrations() {
12
13
  readFileSync(new URL("./migrations/004_load_reconciliation.sql", import.meta.url), "utf8"),
13
14
  readFileSync(new URL("./migrations/005_execution_boundaries.sql", import.meta.url), "utf8"),
14
15
  readFileSync(new URL("./migrations/006_recording_order.sql", import.meta.url), "utf8"),
16
+ readFileSync(new URL("./migrations/007_sync.sql", import.meta.url), "utf8"),
17
+ readFileSync(new URL("./migrations/008_connector_commands.sql", import.meta.url), "utf8"),
15
18
  ];
16
19
  }
17
20
  function userVersion(db) {
@@ -25,6 +28,7 @@ export function openDb(path) {
25
28
  db.exec("PRAGMA journal_mode = WAL");
26
29
  db.exec("PRAGMA busy_timeout = 5000");
27
30
  db.exec("PRAGMA foreign_keys = ON");
31
+ db.exec("PRAGMA recursive_triggers = ON");
28
32
  migrate(db);
29
33
  mergeSplitSessions(db);
30
34
  return db;
@@ -89,6 +93,8 @@ export function migrate(db) {
89
93
  db.exec("BEGIN IMMEDIATE");
90
94
  try {
91
95
  db.exec(sql);
96
+ if (version === 6)
97
+ installJournalTriggers(db);
92
98
  db.exec(`PRAGMA user_version = ${version + 1}`);
93
99
  db.exec("COMMIT");
94
100
  }
@@ -1,4 +1,4 @@
1
- import { assembleSession } from "../analysis/tree.js";
1
+ import * as kernel from "../analysis/kernel.js";
2
2
  import { parseJson } from "./writes.js";
3
3
  /** Local recording cuts resolve equal timestamps, not the runtime's unrecorded causal order. */
4
4
  export function executionEventScope(db, flow, warningSessionIds = [], includeSpanCut = true) {
@@ -122,36 +122,4 @@ function executionBoundarySpans(db, cut) {
122
122
  .map((row) => JSON.stringify([row.trace_id, row.span_id])), unavailable: rows.some((row) => row.position === null) };
123
123
  }
124
124
  /** Keep turn identity from the full assembly, but never carry observations across execution boundaries. */
125
- export function scopeSession(session, scope) {
126
- const { from, to } = scope;
127
- const end = to ?? Number.MAX_SAFE_INTEGER;
128
- const owned = new Set(scope.eventIds);
129
- const inside = (event) => owned.has(event.id);
130
- const turns = session.turns.flatMap((turn, index) => {
131
- const events = turn.events.filter(inside);
132
- if (!events.length)
133
- return [];
134
- const original = new Map(events.map((e) => [e.id, e]));
135
- const endedAt = Math.min(end, session.turns[index + 1]?.startedAt ?? session.endedAt ?? (to ?? turn.endedAt));
136
- const startedAt = Math.max(from, turn.startedAt);
137
- // Reassemble activations from in-window events: the same skill may be activated again in a continuing turn.
138
- // An internal boundary preserves identity when the real prompt preceded registration; it never leaves here.
139
- const scoped = assembleSession({ id: session.id, runtime: session.runtime, startedAt, endedAt, spans: [],
140
- events: [{ id: `execution-boundary:${turn.id}`, ts: startedAt, kind: "prompt", source: "hook",
141
- turnKey: turn.id, callId: null, spanId: null, skillUri: null, text: null, textLength: null, data: {} },
142
- ...events.map((e) => ({ ...e, turnKey: turn.id }))] }).turns[0];
143
- if (!scoped)
144
- return [];
145
- const restore = (event) => {
146
- const source = original.get(event.id);
147
- return source ? { ...event, turnKey: source.turnKey, basis: source.basis } : event;
148
- };
149
- return [{ ...scoped, basis: turn.basis, events: scoped.events.filter((e) => original.has(e.id)).map(restore),
150
- skillSpans: scoped.skillSpans.map((span) => ({ ...span, activation: restore(span.activation), events: span.events.map(restore) })) }];
151
- });
152
- // An execution end clips analysis, never observed lifecycle. A later session end must not rewrite A.
153
- const endedAt = session.endedAt !== null && (session.endedAt < end ||
154
- (session.endedAt === end && scope.sessionEnds?.[session.id] === end)) ? session.endedAt : null;
155
- return { ...session, endedAt,
156
- executionWindow: { from, to }, turns, unassignedEvents: session.unassignedEvents.filter(inside) };
157
- }
125
+ export const scopeSession = kernel.scopeSession;
@@ -1,6 +1,7 @@
1
- import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
1
+ import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
2
2
  import { homedir } from "node:os";
3
3
  import { join, resolve } from "node:path";
4
+ import { DatabaseSync } from "node:sqlite";
4
5
  import { DEFAULT_ROOTS, expandHome } from "../config.js";
5
6
  import { parseJson, readAliasesOverrides, storeError, writeAliasesOverrides } from "./writes.js";
6
7
  export const EXPORT_FILE = "skillar-export.json";
@@ -24,7 +25,10 @@ const HISTORY_TABLES = {
24
25
  };
25
26
  // recording_clock is deliberately local. Row provenance and flow cuts travel
26
27
  // through shared columns; insert triggers add destination arrival provenance.
27
- const HISTORY_VERSIONS = [1, 2, 3, 4, 5, 6];
28
+ // v7 adds local CDC/outbox state; v8 adds connector command receipts.
29
+ // Neither adds portable history tables.
30
+ // Never import its receipts, spool, or source identity into another lineage.
31
+ const HISTORY_VERSIONS = [1, 2, 3, 4, 5, 6, 7, 8];
28
32
  function tildify(path, home) {
29
33
  const h = home.replace(/\/+$/, "");
30
34
  if (path === h)
@@ -140,8 +144,25 @@ export function createPortable(ctx) {
140
144
  const history = join(dir, HISTORY_FILE);
141
145
  rmSync(history, { force: true });
142
146
  if (opts.withHistory) {
143
- db.prepare("VACUUM INTO ?").run(resolve(history));
144
- chmodSync(history, 0o600);
147
+ const temporary = mkdtempSync(join(dir, ".history-"));
148
+ try {
149
+ const snapshot = join(temporary, HISTORY_FILE);
150
+ db.prepare("VACUUM INTO ?").run(resolve(snapshot));
151
+ const portable = new DatabaseSync(snapshot);
152
+ try {
153
+ // Source-local replay results must not enter the portable artifact,
154
+ // including free pages. Keep the live source receipts intact.
155
+ portable.exec("PRAGMA secure_delete=ON; DELETE FROM connector_command_receipts; VACUUM;");
156
+ }
157
+ finally {
158
+ portable.close();
159
+ }
160
+ chmodSync(snapshot, 0o600);
161
+ renameSync(snapshot, history);
162
+ }
163
+ finally {
164
+ rmSync(temporary, { recursive: true, force: true });
165
+ }
145
166
  }
146
167
  },
147
168
  importFrom(dir, opts) {
@@ -0,0 +1,49 @@
1
+ -- Local raw history is not a cloud payload. Consent is applied before outbox insertion.
2
+ CREATE TABLE sync_identity (
3
+ singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
4
+ source_domain TEXT NOT NULL UNIQUE
5
+ );
6
+ INSERT INTO sync_identity SELECT 1, domain FROM recording_clock WHERE singleton = 1;
7
+
8
+ CREATE TABLE sync_journal (
9
+ seq INTEGER PRIMARY KEY AUTOINCREMENT CHECK (seq <= 9007199254740991),
10
+ table_name TEXT NOT NULL,
11
+ entity_key TEXT NOT NULL,
12
+ operation TEXT NOT NULL CHECK (operation IN ('upsert', 'delete')),
13
+ source_order INTEGER,
14
+ row_json TEXT,
15
+ before_json TEXT,
16
+ CHECK ((operation = 'delete') = (row_json IS NULL))
17
+ );
18
+ CREATE INDEX sync_journal_entity ON sync_journal(table_name, entity_key, seq);
19
+ -- RAISE(ABORT) must defeat an outer INSERT OR IGNORE on counter exhaustion.
20
+ CREATE TRIGGER sync_journal_range BEFORE INSERT ON sync_journal
21
+ WHEN COALESCE((SELECT seq FROM sqlite_sequence WHERE name='sync_journal'),0) >= 9007199254740991
22
+ BEGIN
23
+ SELECT RAISE(ABORT, 'sync journal exhausted');
24
+ END;
25
+
26
+ CREATE TABLE sync_streams (
27
+ stream_id TEXT PRIMARY KEY,
28
+ source_domain TEXT NOT NULL,
29
+ device_id TEXT NOT NULL,
30
+ next_sequence INTEGER NOT NULL DEFAULT 1 CHECK (next_sequence BETWEEN 1 AND 9007199254740991),
31
+ ack_sequence INTEGER NOT NULL DEFAULT 0,
32
+ ack_hash TEXT,
33
+ ack_cut INTEGER NOT NULL DEFAULT 0,
34
+ CHECK (ack_sequence < next_sequence)
35
+ );
36
+ CREATE TABLE sync_outbox (
37
+ stream_id TEXT NOT NULL REFERENCES sync_streams(stream_id),
38
+ sequence INTEGER NOT NULL,
39
+ batch_id TEXT NOT NULL UNIQUE,
40
+ payload TEXT NOT NULL,
41
+ payload_hash TEXT NOT NULL,
42
+ payload_bytes INTEGER NOT NULL CHECK (payload_bytes BETWEEN 1 AND 262144),
43
+ journal_from INTEGER NOT NULL,
44
+ journal_through INTEGER NOT NULL CHECK (journal_through >= journal_from),
45
+ PRIMARY KEY (stream_id, sequence)
46
+ );
47
+ CREATE TRIGGER sync_outbox_immutable BEFORE UPDATE ON sync_outbox BEGIN
48
+ SELECT RAISE(ABORT, 'sync outbox is immutable');
49
+ END;
@@ -0,0 +1,12 @@
1
+ -- These receipts are local authority, not replicated source content.
2
+ -- Keep them across disconnect/reconnect and source data retention.
3
+ CREATE TABLE connector_command_receipts (
4
+ account_id TEXT NOT NULL,
5
+ generation INTEGER NOT NULL,
6
+ device_id TEXT NOT NULL,
7
+ source_domain TEXT NOT NULL,
8
+ command_id TEXT NOT NULL,
9
+ payload_hash TEXT NOT NULL,
10
+ result_json TEXT NOT NULL,
11
+ PRIMARY KEY (account_id, generation, device_id, source_domain, command_id)
12
+ );
@@ -1,3 +1,4 @@
1
+ import { requestRecords, summarizeRequests, hasStatus } from "../request-status.js";
1
2
  import { existsSync, readFileSync } from "node:fs";
2
3
  import { automationOf, NO_ACTIVITY } from "./automation.js";
3
4
  import { executionEventScope } from "./execution.js";
@@ -191,7 +192,10 @@ export function createQueries(ctx) {
191
192
  texts.push(e.text);
192
193
  });
193
194
  const attributed = evs.find((e) => e.attribution_method !== "none");
195
+ const records = requestRecords(evs.map((e, i) => ({ id: e.id, ts: e.ts, kind: e.kind, data: parsed[i].data, ...(e.skill_uri ? { skillUri: e.skill_uri } : {}) })));
196
+ const requests = summarizeRequests(records);
194
197
  const info = {
198
+ requests, requestRecords: records,
195
199
  id: r.id, runtime: r.runtime, startedAt: r.started_at, events: evs, loaded, exposed, state: adoptionState(parsed),
196
200
  attribution: attributed?.attribution_method ?? "none", texts,
197
201
  ...(r.ended_at !== null ? { endedAt: r.ended_at } : {}),
@@ -200,7 +204,7 @@ export function createQueries(ctx) {
200
204
  };
201
205
  // A session with no prompt and no skill activity (e.g. a thread the Codex daemon reopened) tells nothing about usage.
202
206
  const active = loaded.length > 0 || exposed.length > 0
203
- || evs.some((e) => e.kind === "prompt" || e.kind === "native_skill" || e.kind === "read_file");
207
+ || evs.some((e) => e.kind === "prompt" || e.kind === "native_skill" || e.kind === "read_file" || e.kind === "skill_request" || e.kind === "search");
204
208
  const automated = automationIdOf(info.firstPrompt, active);
205
209
  if (automated !== undefined)
206
210
  info.automated = automated;
@@ -208,9 +212,15 @@ export function createQueries(ctx) {
208
212
  continue;
209
213
  if (f.automated === "only" && automated === undefined)
210
214
  continue;
215
+ if (f.searchStatus?.length && !f.searchStatus.some((status) => hasStatus(requests.search, status)))
216
+ continue;
217
+ if (f.loadStatus?.length && !f.loadStatus.some((status) => hasStatus(requests.load, status)))
218
+ continue;
219
+ if (f.searchResult?.length && !f.searchResult.some((result) => requests.search.results[result] > 0))
220
+ continue;
211
221
  if (f.state && f.state.length > 0 && !f.state.includes(info.state))
212
222
  continue;
213
- if (f.skill && f.skill.length > 0 && !f.skill.some((u) => loaded.includes(u) || exposed.includes(u)))
223
+ if (f.skill && f.skill.length > 0 && !f.skill.some((u) => loaded.includes(u) || exposed.includes(u) || records.some((r) => r.uri === u)))
214
224
  continue;
215
225
  if (f.q) {
216
226
  const q = f.q.toLowerCase();
@@ -381,7 +391,7 @@ export function createQueries(ctx) {
381
391
  return loadSessions(f)
382
392
  .sort((a, b) => b.startedAt - a.startedAt)
383
393
  .map((s) => ({
384
- id: s.id, runtime: s.runtime, startedAt: s.startedAt, skills: sessionSkills(s), state: s.state, attribution: s.attribution,
394
+ id: s.id, runtime: s.runtime, startedAt: s.startedAt, requests: s.requests, skills: sessionSkills(s), state: s.state, attribution: s.attribution,
385
395
  ...(s.endedAt !== undefined ? { endedAt: s.endedAt } : {}),
386
396
  ...(s.firstPrompt !== undefined ? { firstPrompt: s.firstPrompt } : {}),
387
397
  ...(s.automated !== undefined ? { automated: s.automated } : {}),
@@ -399,6 +409,7 @@ export function createQueries(ctx) {
399
409
  loadsByTrace.set(e.trace_id, list);
400
410
  }
401
411
  const loadRow = db.prepare("SELECT uri, manifest_digest FROM loads WHERE load_id = ?");
412
+ const requestOutcomes = new Map(requestRecords(evs.map((e) => ({ id: e.id, ts: e.ts, kind: e.kind, data: parseJson(e.data_json, {}) }))).map((r) => [r.id, r]));
402
413
  return evs.map((e) => {
403
414
  const data = parseJson(e.data_json, {});
404
415
  switch (e.kind) {
@@ -425,7 +436,7 @@ export function createQueries(ctx) {
425
436
  const uri = e.skill_uri ?? stored?.uri ?? (typeof data.uri === "string" ? data.uri : "");
426
437
  const manifestDigest = typeof data.manifestDigest === "string" ? data.manifestDigest : stored?.manifest_digest ?? "";
427
438
  return { ts: e.ts, kind: e.kind, summary: `load ${metaFor(skills, uri).name} (${uri}) @${shortDigest(manifestDigest)}`,
428
- detail: { kind: "load", uri, loadId, manifestDigest } };
439
+ detail: { ...data, kind: "load", uri, loadId, manifestDigest } };
429
440
  }
430
441
  case "read_file": {
431
442
  const uri = typeof data.uri === "string" ? data.uri : "";
@@ -452,10 +463,14 @@ export function createQueries(ctx) {
452
463
  ...(e.tool_use_id !== null ? { toolUseId: e.tool_use_id } : {}), ...(e.call_id !== null ? { callId: e.call_id } : {}),
453
464
  ...(e.text !== null ? { args: e.text } : {}), ...(e.text_length !== null ? { argsLength: e.text_length } : {}) } };
454
465
  }
466
+ case "skill_request": {
467
+ const record = requestOutcomes.get(String(data.requestId));
468
+ return { ts: e.ts, kind: e.kind, summary: `${data.operation} request: ${record?.status ?? "unknown"}`, detail: { ...data, kind: e.kind, currentStatus: record?.status ?? "unknown" } };
469
+ }
455
470
  case "error": {
456
471
  const code = typeof data.code === "string" ? data.code : "error";
457
472
  const message = typeof data.message === "string" ? data.message : e.text ?? "";
458
- return { ts: e.ts, kind: e.kind, summary: `error ${code}${message ? `: ${message.slice(0, 200)}` : ""}`, detail: { kind: "error", code, message } };
473
+ return { ts: e.ts, kind: e.kind, summary: `error ${code}${message ? `: ${message.slice(0, 200)}` : ""}`, detail: { ...data, ...(e.skill_uri ? { uri: e.skill_uri } : {}), kind: "error", code, message } };
459
474
  }
460
475
  default:
461
476
  return { ts: e.ts, kind: e.kind, summary: e.kind === "session_start" ? "session started" : "session ended", detail: { kind: e.kind } };
@@ -470,6 +485,17 @@ export function createQueries(ctx) {
470
485
  for (const s of sessions) {
471
486
  const primary = s.loaded[0] ?? s.firstTop;
472
487
  const task = classifyTaskType(primary ? metaFor(skills, primary) : undefined, s.firstPrompt ?? s.texts[0]);
488
+ if (unit === "search_requests" || unit === "load_requests") {
489
+ const operation = unit === "search_requests" ? "search" : "load";
490
+ const statuses = operation === "search" ? f.searchStatus : f.loadStatus;
491
+ for (const request of s.requestRecords.filter((r) => r.operation === operation
492
+ && (!statuses?.length || statuses.includes(r.status))
493
+ && (!f.skill?.length || r.uri !== undefined && f.skill.includes(r.uri))
494
+ && (operation !== "search" || !f.searchResult?.length || r.result !== undefined && f.searchResult.includes(r.result)))) {
495
+ paths.push({ session: `${s.id}:${request.id}`, task, skill: request.uri ?? "(none)", state: request.status });
496
+ }
497
+ continue;
498
+ }
473
499
  const skillList = unit === "all_loads" && s.loaded.length > 0 ? s.loaded : primary ? [primary] : ["(none)"];
474
500
  for (const sk of skillList)
475
501
  paths.push({ session: s.id, task, skill: sk, state: s.state });
@@ -512,7 +538,7 @@ export function createQueries(ctx) {
512
538
  };
513
539
  const before = countLinks();
514
540
  for (const p of mapped) {
515
- if (p.skill === OTHER)
541
+ if (p.skill === OTHER || unit.endsWith("_requests"))
516
542
  continue;
517
543
  const weakLeft = (before.left.get(`${p.task}\u0000${p.skill}\u0000${p.state}`)?.size ?? 0) < 2;
518
544
  const weakRight = (before.right.get(`${p.skill}\u0000${p.stateNode}\u0000${p.state}`)?.size ?? 0) < 2;
@@ -549,7 +575,7 @@ export function createQueries(ctx) {
549
575
  links.push({ source: nodeId(1, skill), target: nodeId(2, stateNode), count: set.size, state });
550
576
  }
551
577
  links.sort((a, b) => b.count - a.count);
552
- return { unit, columns: ["task_type", "skill", "state"], nodes, links, sessionCount: sessions.length };
578
+ return { ...(unit.endsWith("_requests") ? { requestCount: paths.length } : {}), unit, columns: ["task_type", "skill", "state"], nodes, links, sessionCount: sessions.length };
553
579
  },
554
580
  heatmap(f, tz, weekStart, bucketHours) {
555
581
  const buckets = 24 / bucketHours;