@anchrd/intel-contract 0.1.0

package/dist/contract/contract.js

@@ -0,0 +1,462 @@
+import { z } from "zod";
+export const IntelId = z.string().min(1).max(128);
+export const IsoDateTime = z.iso.datetime({ offset: true });
+export const ProblemDetails = z.strictObject({
+    type: z.string(),
+    status: z.number().int().min(400).max(599),
+    title: z.string(),
+    detail: z.string().optional(),
+    instance: z.string().optional(),
+    code: z.string().optional(),
+});
+export const KnowledgeNodeKind = z.enum(["folder", "document", "attachment"]);
+export const ContextPolicy = z.enum(["pinned", "relevant", "explicit"]);
+export const ResourceRole = z.enum(["viewer", "commenter", "editor", "manager"]);
+export const SharePrincipal = z.discriminatedUnion("type", [
+    z.strictObject({ type: z.literal("user"), id: IntelId }),
+    z.strictObject({ type: z.literal("email"), email: z.email() }),
+    z.strictObject({ type: z.literal("organization") }),
+]);
+export const KnowledgeNode = z.strictObject({
+    id: IntelId,
+    parentId: IntelId.nullable(),
+    kind: KnowledgeNodeKind,
+    title: z.string().min(1).max(240),
+    description: z.string().max(2_000).nullable(),
+    contextPolicy: ContextPolicy,
+    ownerId: IntelId,
+    currentVersionId: IntelId.nullable(),
+    createdAt: IsoDateTime,
+    updatedAt: IsoDateTime,
+    archivedAt: IsoDateTime.nullable(),
+});
+export const KnowledgeVersion = z.strictObject({
+    id: IntelId,
+    nodeId: IntelId,
+    sequence: z.number().int().positive(),
+    contentKey: z.string().min(1),
+    mediaType: z.string().min(1).max(160),
+    contentHash: z.string().regex(/^[a-f0-9]{64}$/),
+    size: z.number().int().nonnegative(),
+    createdBy: IntelId,
+    createdAt: IsoDateTime,
+});
+export const ListKnowledgeNodesInput = z.strictObject({
+    parentId: IntelId.nullable().default(null),
+    includeArchived: z.boolean().default(false),
+});
+export const GetKnowledgeNodeInput = z.strictObject({ nodeId: IntelId });
+export const ListKnowledgeGrantsInput = z.strictObject({ resourceId: IntelId });
+export const CreateKnowledgeNodeInput = z.strictObject({
+    parentId: IntelId.nullable().default(null),
+    kind: KnowledgeNodeKind,
+    title: z.string().trim().min(1).max(240),
+    description: z.string().trim().max(2_000).nullable().default(null),
+    contextPolicy: ContextPolicy.default("relevant"),
+    idempotencyKey: z.string().min(8).max(200),
+});
+export const SaveKnowledgeVersionInput = z.strictObject({
+    nodeId: IntelId,
+    baseVersionId: IntelId.nullable(),
+    content: z.string().max(10_000_000),
+    mediaType: z.string().min(1).max(160).default("text/markdown"),
+    idempotencyKey: z.string().min(8).max(200),
+});
+export const SaveKnowledgeAttachmentInput = z.strictObject({
+    nodeId: IntelId,
+    baseVersionId: IntelId.nullable(),
+    contentBase64: z.string().min(1).max(20_000_000),
+    mediaType: z.string().min(1).max(160),
+    idempotencyKey: z.string().min(8).max(200),
+});
+export const UpdateKnowledgeNodeInput = z
+    .strictObject({
+    nodeId: IntelId,
+    baseUpdatedAt: IsoDateTime,
+    title: z.string().trim().min(1).max(240).optional(),
+    description: z.string().trim().max(2_000).nullable().optional(),
+    contextPolicy: ContextPolicy.optional(),
+    parentId: IntelId.nullable().optional(),
+    idempotencyKey: z.string().min(8).max(200),
+})
+    .refine((input) => input.title !== undefined ||
+    input.description !== undefined ||
+    input.contextPolicy !== undefined ||
+    input.parentId !== undefined, { message: "At least one change is required" });
+export const ArchiveKnowledgeNodeInput = z.strictObject({
+    nodeId: IntelId,
+    baseUpdatedAt: IsoDateTime,
+    archived: z.boolean(),
+    idempotencyKey: z.string().min(8).max(200),
+});
+export const KnowledgeNodeList = z.strictObject({ items: z.array(KnowledgeNode) });
+export const KnowledgeVersionList = z.strictObject({ items: z.array(KnowledgeVersion) });
+export const KnowledgeDocument = z.strictObject({
+    node: KnowledgeNode,
+    version: KnowledgeVersion.nullable(),
+    content: z.string().nullable(),
+});
+export const KnowledgeAttachment = z.strictObject({
+    node: KnowledgeNode,
+    version: KnowledgeVersion,
+    resourceUri: z.string().regex(/^intel:\/\/knowledge\/[^/]+\/attachment$/),
+});
+export const KnowledgeLinkRelation = z.enum(["references", "related", "depends_on", "implements"]);
+export const KnowledgeLink = z.strictObject({
+    id: IntelId,
+    sourceNodeId: IntelId,
+    targetNodeId: IntelId,
+    relation: KnowledgeLinkRelation,
+    label: z.string().trim().min(1).max(120).nullable(),
+    createdBy: IntelId,
+    createdAt: IsoDateTime,
+});
+export const KnowledgeLinkList = z.strictObject({ items: z.array(KnowledgeLink) });
+export const CreateKnowledgeLinkInput = z
+    .strictObject({
+    sourceNodeId: IntelId,
+    targetNodeId: IntelId,
+    relation: KnowledgeLinkRelation,
+    label: z.string().trim().min(1).max(120).nullable().default(null),
+    idempotencyKey: z.string().min(8).max(200),
+})
+    .refine((input) => input.sourceNodeId !== input.targetNodeId, {
+    message: "Knowledge cannot link to itself",
+});
+export const DeleteKnowledgeLinkInput = z.strictObject({
+    sourceNodeId: IntelId,
+    linkId: IntelId,
+    idempotencyKey: z.string().min(8).max(200),
+});
+export const KnowledgeGraphInput = z.strictObject({
+    limit: z.number().int().min(1).max(500).default(250),
+});
+export const KnowledgeGraph = z.strictObject({
+    nodes: z.array(KnowledgeNode),
+    links: z.array(KnowledgeLink),
+});
+export const BlockNoteMediaType = "application/vnd.anchrd.intel.blocknote+json";
+export const BlockNoteDocument = z.strictObject({
+    format: z.literal("blocknote"),
+    schemaVersion: z.literal(1),
+    blocks: z.array(z.record(z.string(), z.unknown())),
+    markdown: z.string(),
+});
+export const ResourceGrant = z.strictObject({
+    id: IntelId,
+    resourceId: IntelId,
+    principal: SharePrincipal,
+    role: ResourceRole,
+    expiresAt: IsoDateTime.nullable(),
+    createdBy: IntelId,
+    createdAt: IsoDateTime,
+});
+export const ShareKnowledgeInput = z.strictObject({
+    resourceId: IntelId,
+    principal: SharePrincipal,
+    role: ResourceRole,
+    expiresAt: IsoDateTime.nullable().default(null),
+    idempotencyKey: z.string().min(8).max(200),
+});
+export const RevokeKnowledgeGrantInput = z.strictObject({
+    resourceId: IntelId,
+    grantId: IntelId,
+    idempotencyKey: z.string().min(8).max(200),
+});
+export const ResourceGrantList = z.strictObject({ items: z.array(ResourceGrant) });
+export const SearchKnowledgeInput = z.strictObject({
+    query: z.string().trim().min(1).max(500),
+    limit: z.number().int().min(1).max(50).default(10),
+});
+export const KnowledgeCitation = z.strictObject({
+    nodeId: IntelId,
+    versionId: IntelId,
+    title: z.string(),
+    passage: z.string(),
+    source: z.string(),
+    freshness: IsoDateTime,
+    score: z.number().min(0).max(1),
+    match: z.enum(["lexical", "semantic", "hybrid"]),
+});
+export const SearchKnowledgeResult = z.strictObject({
+    items: z.array(KnowledgeCitation),
+});
+export const ReindexKnowledgeResult = z.strictObject({ queued: z.number().int().nonnegative() });
+export const RevokeGrantResult = z.strictObject({ revoked: z.boolean() });
+export const DeleteKnowledgeLinkResult = z.strictObject({ deleted: z.boolean() });
+function isPrivateIpv4(hostname) {
+    const parts = hostname.split(".").map(Number);
+    if (parts.length !== 4 ||
+        parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
+        return false;
+    }
+    const [first = 0, second = 0] = parts;
+    return (first === 0 ||
+        first === 10 ||
+        first === 127 ||
+        (first === 100 && second >= 64 && second <= 127) ||
+        (first === 169 && second === 254) ||
+        (first === 172 && second >= 16 && second <= 31) ||
+        (first === 192 && second === 168) ||
+        (first === 198 && (second === 18 || second === 19)) ||
+        first >= 224);
+}
+function normalizedHostname(url) {
+    return url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+}
+function isPublicToolHost(url) {
+    const hostname = normalizedHostname(url);
+    if (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1") {
+        return url.protocol === "http:";
+    }
+    if (!hostname.includes(".") ||
+        hostname.endsWith(".local") ||
+        hostname.endsWith(".localhost") ||
+        hostname.endsWith(".internal") ||
+        isPrivateIpv4(hostname) ||
+        hostname.includes(":")) {
+        return false;
+    }
+    return url.protocol === "https:";
+}
+export const ToolSourceUrl = z.url().refine((value) => {
+    try {
+        const url = new URL(value);
+        return !url.username && !url.password && isPublicToolHost(url);
+    }
+    catch {
+        return false;
+    }
+}, "Tool source must use an approved public HTTPS host without embedded credentials");
+export const ToolSource = z.strictObject({
+    id: IntelId,
+    name: z.string().min(1).max(120),
+    url: ToolSourceUrl,
+    connectionHandle: z.string().regex(/^[a-z0-9][a-z0-9-]{1,62}$/),
+    enabled: z.boolean(),
+    createdBy: IntelId,
+    createdAt: IsoDateTime,
+    updatedAt: IsoDateTime,
+    lastDiscoveredAt: IsoDateTime.nullable(),
+});
+export const ToolAnnotations = z.strictObject({
+    title: z.string().max(240).optional(),
+    readOnlyHint: z.boolean().optional(),
+    destructiveHint: z.boolean().optional(),
+    idempotentHint: z.boolean().optional(),
+    openWorldHint: z.boolean().optional(),
+});
+export const ToolCapability = z.strictObject({
+    sourceId: IntelId,
+    name: z.string().min(1).max(240),
+    title: z.string().max(240).nullable(),
+    description: z.string().max(10_000).nullable(),
+    inputSchema: z.record(z.string(), z.unknown()),
+    outputSchema: z.record(z.string(), z.unknown()).nullable(),
+    annotations: ToolAnnotations,
+    fingerprint: z.string().regex(/^[a-f0-9]{64}$/),
+    discoveredAt: IsoDateTime,
+});
+export const ToolConnectionStatus = z.enum(["connected", "missing", "forbidden", "invalid"]);
+export const ToolCatalogEntry = z.strictObject({
+    source: ToolSource,
+    capability: ToolCapability,
+    connectionStatus: ToolConnectionStatus,
+});
+export const ToolSourceList = z.strictObject({ items: z.array(ToolSource) });
+export const ToolCatalog = z.strictObject({ items: z.array(ToolCatalogEntry) });
+export const CreateToolSourceInput = z.strictObject({
+    name: z.string().trim().min(1).max(120),
+    url: ToolSourceUrl,
+    connectionHandle: z
+        .string()
+        .regex(/^[a-z0-9][a-z0-9-]{1,62}$/)
+        .default("intel-tools"),
+    idempotencyKey: z.string().min(8).max(200),
+});
+export const DiscoverToolSourceInput = z.strictObject({
+    sourceId: IntelId,
+    idempotencyKey: z.string().min(8).max(200),
+});
+export const TestToolInput = z.strictObject({
+    sourceId: IntelId,
+    name: z.string().min(1).max(240),
+    arguments: z.record(z.string(), z.unknown()).default({}),
+});
+export const ExecuteToolInput = TestToolInput;
+export const ToolTestResult = z.strictObject({
+    isError: z.boolean(),
+    content: z.array(z.unknown()),
+    structuredContent: z.unknown().optional(),
+});
+export const FlowNodeId = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$/);
+export const FlowPosition = z.strictObject({ x: z.number().finite(), y: z.number().finite() });
+const FlowNodeBase = {
+    id: FlowNodeId,
+    position: FlowPosition,
+    label: z.string().trim().min(1).max(160),
+    description: z.string().trim().max(2_000).nullable().default(null),
+};
+export const FlowNode = z.discriminatedUnion("kind", [
+    z.strictObject({
+        ...FlowNodeBase,
+        kind: z.literal("trigger"),
+        configuration: z.discriminatedUnion("mode", [
+            z.strictObject({ mode: z.literal("manual") }),
+            z.strictObject({ mode: z.literal("webhook"), event: z.string().min(1).max(120) }),
+            z.strictObject({ mode: z.literal("schedule"), cron: z.string().min(5).max(120) }),
+        ]),
+    }),
+    z.strictObject({
+        ...FlowNodeBase,
+        kind: z.literal("instruction"),
+        configuration: z.strictObject({ prompt: z.string().min(1).max(50_000) }),
+    }),
+    z.strictObject({
+        ...FlowNodeBase,
+        kind: z.literal("knowledge"),
+        configuration: z.strictObject({
+            resourceIds: z.array(IntelId).min(1).max(100),
+            mode: z.enum(["full", "relevant"]),
+            query: z.string().max(1_000).nullable().default(null),
+        }),
+    }),
+    z.strictObject({
+        ...FlowNodeBase,
+        kind: z.literal("tool"),
+        configuration: z.strictObject({
+            sourceId: IntelId,
+            toolName: z.string().min(1).max(240),
+            fingerprint: z
+                .string()
+                .regex(/^[a-f0-9]{64}$/)
+                .nullable()
+                .default(null),
+            arguments: z.record(z.string(), z.unknown()).default({}),
+        }),
+    }),
+    z.strictObject({
+        ...FlowNodeBase,
+        kind: z.literal("condition"),
+        configuration: z.strictObject({
+            mode: z.literal("semantic"),
+            instruction: z.string().min(1).max(10_000),
+        }),
+    }),
+    z.strictObject({
+        ...FlowNodeBase,
+        kind: z.literal("approval"),
+        configuration: z.strictObject({
+            prompt: z.string().min(1).max(10_000),
+            timeout: z.string().regex(/^\d+\s+(minute|minutes|hour|hours|day|days)$/),
+        }),
+    }),
+    z.strictObject({
+        ...FlowNodeBase,
+        kind: z.literal("output"),
+        configuration: z.strictObject({ template: z.string().max(50_000).default("") }),
+    }),
+]);
+export const FlowEdge = z.strictObject({
+    id: FlowNodeId,
+    source: FlowNodeId,
+    target: FlowNodeId,
+    label: z.string().trim().min(1).max(120).nullable().default(null),
+    sourceHandle: z.string().trim().min(1).max(120).nullable().default(null),
+});
+export const FlowGraph = z.strictObject({
+    nodes: z.array(FlowNode).min(2).max(200),
+    edges: z.array(FlowEdge).min(1).max(500),
+});
+export const Flow = z.strictObject({
+    id: IntelId,
+    title: z.string().min(1).max(240),
+    description: z.string().max(2_000).nullable(),
+    ownerId: IntelId,
+    currentVersionId: IntelId.nullable(),
+    publishedVersionId: IntelId.nullable(),
+    createdAt: IsoDateTime,
+    updatedAt: IsoDateTime,
+    archivedAt: IsoDateTime.nullable(),
+});
+export const FlowVersion = z.strictObject({
+    id: IntelId,
+    flowId: IntelId,
+    sequence: z.number().int().positive(),
+    graph: FlowGraph,
+    createdBy: IntelId,
+    createdAt: IsoDateTime,
+});
+export const FlowDocument = z.strictObject({
+    flow: Flow,
+    version: FlowVersion.nullable(),
+});
+export const FlowList = z.strictObject({ items: z.array(Flow) });
+export const CreateFlowInput = z.strictObject({
+    title: z.string().trim().min(1).max(240),
+    description: z.string().trim().max(2_000).nullable().default(null),
+    idempotencyKey: z.string().min(8).max(200),
+});
+export const GetFlowInput = z.strictObject({ flowId: IntelId });
+export const SaveFlowVersionInput = z.strictObject({
+    flowId: IntelId,
+    baseVersionId: IntelId.nullable(),
+    graph: FlowGraph,
+    idempotencyKey: z.string().min(8).max(200),
+});
+export const PublishFlowInput = z.strictObject({
+    flowId: IntelId,
+    versionId: IntelId,
+    idempotencyKey: z.string().min(8).max(200),
+});
+export const ListFlowGrantsInput = z.strictObject({ resourceId: IntelId });
+export const ShareFlowInput = z.strictObject({
+    resourceId: IntelId,
+    principal: SharePrincipal,
+    role: ResourceRole,
+    expiresAt: IsoDateTime.nullable().default(null),
+    idempotencyKey: z.string().min(8).max(200),
+});
+export const RevokeFlowGrantInput = z.strictObject({
+    resourceId: IntelId,
+    grantId: IntelId,
+    idempotencyKey: z.string().min(8).max(200),
+});
+export const FlowRunStatus = z.enum([
+    "queued",
+    "running",
+    "waiting",
+    "completed",
+    "failed",
+    "cancelled",
+]);
+export const FlowRun = z.strictObject({
+    id: IntelId,
+    flowId: IntelId,
+    versionId: IntelId,
+    status: FlowRunStatus,
+    currentNodeId: FlowNodeId.nullable(),
+    input: z.record(z.string(), z.unknown()),
+    output: z.unknown().nullable(),
+    error: z.string().max(2_000).nullable(),
+    initiatedBy: IntelId,
+    createdAt: IsoDateTime,
+    updatedAt: IsoDateTime,
+    completedAt: IsoDateTime.nullable(),
+});
+export const FlowRunStep = z.strictObject({ run: FlowRun, node: FlowNode.nullable() });
+export const StartFlowRunInput = z.strictObject({
+    flowId: IntelId,
+    input: z.record(z.string(), z.unknown()).default({}),
+    idempotencyKey: z.string().min(8).max(200),
+});
+export const GetFlowRunInput = z.strictObject({ runId: IntelId });
+export const CompleteFlowRunStepInput = z.strictObject({
+    runId: IntelId,
+    nodeId: FlowNodeId,
+    outcome: z.enum(["completed", "failed"]),
+    branch: z.string().min(1).max(120).nullable().default(null),
+    output: z.unknown().nullable().default(null),
+    error: z.string().max(2_000).nullable().default(null),
+    idempotencyKey: z.string().min(8).max(200),
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@anchrd/intel-contract",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anchrd/intel.git",
+    "directory": "packages/contract"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/contract/contract.d.ts",
+      "default": "./dist/contract/contract.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node ../../scripts/pack/fix-dts.mjs",
+    "prepack": "bun run build && node ../../scripts/pack/to-dist-manifest.mjs",
+    "postpack": "node ../../scripts/pack/restore-manifest.mjs",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.10"
+  },
+  "main": "./dist/contract/contract.js",
+  "module": "./dist/contract/contract.js",
+  "types": "./dist/contract/contract.d.ts"
+}