@anchrd/intel-contract 0.18.0 → 0.20.0

package/README.md

@@ -95,10 +95,15 @@ edge and the tool ends up in the chain. The graph is then refused with
 `Node <id> is a link and must be attached to a step` — in `title`, per the first item above. A step
 may hold several links; one link belongs to exactly one step.
 
-### A flow is not a node, and carries no grants of its own
+### A flow is not a node, and has its own grant calls
 
-`node_grant_create` addresses nodes. A flow has no grants; it inherits those of the folder it lives
-in. To change who reaches a flow, share its folder — or move the flow.
+`node_grant_create` addresses nodes; `flow_grant_create` addresses flows. A flow is reached by both:
+the folder it is filed in passes its grants down, and a grant may sit on the flow itself. The two
+add up — the flow grant never replaces what the folder passes down.
+
+⚠️ A grant on one flow reaches **that flow** and nothing else — not the folder, and not the flows it
+calls. `ShareResult` says so: `unrunnable` names the sub-flows the new principal could not start,
+by title where you may see them and by count where you may not.
 
 ### Import takes its idempotency key as a header
 

package/dist/contract/flow.d.ts

@@ -899,6 +899,21 @@ export declare const FlowPublishCall: z.ZodObject<{
     available: z.ZodBoolean;
 }, z.core.$strict>;
 export type FlowPublishCall = z.infer<typeof FlowPublishCall>;
+/**
+ * What a tool step will be allowed to reach once this version is published (#517).
+ *
+ * ⚠️ It is in the preview because publishing FREEZES it: from that moment the step's surface is
+ * pinned, and a function the provider adds later is not inherited. An author who cannot see the
+ * surface before confirming is asked to freeze something they were never shown.
+ */
+export declare const FlowPublishTool: z.ZodObject<{
+    nodeId: z.ZodString;
+    nodeLabel: z.ZodString;
+    server: z.ZodString;
+    allow: z.ZodNullable<z.ZodArray<z.ZodString>>;
+    available: z.ZodBoolean;
+}, z.core.$strict>;
+export type FlowPublishTool = z.infer<typeof FlowPublishTool>;
 export declare const FlowPublishPreview: z.ZodObject<{
     flowId: z.ZodString;
     versionId: z.ZodString;
@@ -917,6 +932,13 @@ export declare const FlowPublishPreview: z.ZodObject<{
         freezes: z.ZodBoolean;
         available: z.ZodBoolean;
     }, z.core.$strict>>;
+    tools: z.ZodArray<z.ZodObject<{
+        nodeId: z.ZodString;
+        nodeLabel: z.ZodString;
+        server: z.ZodString;
+        allow: z.ZodNullable<z.ZodArray<z.ZodString>>;
+        available: z.ZodBoolean;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export type FlowPublishPreview = z.infer<typeof FlowPublishPreview>;
 export declare const RelationNodeKind: z.ZodEnum<{

package/dist/contract/flow.js

@@ -86,8 +86,18 @@ export const FlowNode = z.discriminatedUnion("kind", [
      * step's instruction and can only be known while the flow runs.
      *
      * `allow: null` means every function of that server. A list narrows it, and every entry has to
-     * belong to `server` — checked below, because a name from another server would silently widen
-     * the step past the one thing this configuration is supposed to bound.
+     * belong to `server` — checked below, because a name from another server would make the step ask
+     * for something the portal routes somewhere else entirely.
+     *
+     * ⚠️ `allow` is an INSTRUCTION to the agent, not a boundary Intel enforces (#518). Intel is a
+     * library: it says what is to be done, it does not execute. A flow is carried out by an agent
+     * that reaches the portal with its OWN token, and that agent may call the portal directly —
+     * Intel never sees the call. What bounds it is the agent's own portal grant, checked by the
+     * portal on every call; what `allow` does is tell the agent which of those functions this step
+     * is meant to use, the same way an instruction step tells it what to write.
+     *
+     * That is not a gap to be closed by adding a check here. Enforcing it would mean routing every
+     * call through Intel and making it the executor — the one thing this product is not.
      *
      * ⚠️ There is deliberately no `arguments` field any more. Arguments are produced at run time and
      * validated against the tool's own `inputSchema` from a live `tools/list`; a stored copy would be
@@ -405,14 +415,32 @@ export const FlowPublishCall = z.strictObject({
     // The callee has a published version to be called at all. `false` is what publishing will refuse.
     available: z.boolean(),
 });
+/**
+ * What a tool step will be allowed to reach once this version is published (#517).
+ *
+ * ⚠️ It is in the preview because publishing FREEZES it: from that moment the step's surface is
+ * pinned, and a function the provider adds later is not inherited. An author who cannot see the
+ * surface before confirming is asked to freeze something they were never shown.
+ */
+export const FlowPublishTool = z.strictObject({
+    nodeId: FlowNodeId,
+    nodeLabel: z.string().min(1).max(160),
+    server: ToolServerHandle,
+    // `null` is "every function of that server". A list is what the step narrowed itself to, and it
+    // is spelled out rather than counted: the whole point of the preview is that a human can read it.
+    allow: z.array(ToolName).nullable(),
+    // The server is reachable for the person publishing. `false` is what publishing will refuse.
+    available: z.boolean(),
+});
 export const FlowPublishPreview = z.strictObject({
     flowId: IntelId,
     versionId: IntelId,
     calls: z.array(FlowPublishCall),
+    tools: z.array(FlowPublishTool),
 });
-// A flow has no share schema of its own. A grant sits on the folder a flow is filed in and inherits
-// down from there (ADR-0004 §2); a narrower grant beside it would destroy the subtree guarantee
-// section 3 rests on, so per-flow grants were removed rather than deprecated.
+// A flow's own sharing schemas live in `share.ts` beside the node's (#530): `ShareFlowInput`,
+// `RevokeFlowGrantInput`, `ListFlowGrantsInput`. They are there rather than here because a grant is
+// one subject with two kinds of target, not two features — and `ShareResult` answers for both.
 // What accesses what, for one level of the shared tree (#19). A folder answers it for its contents,
 // a single flow for itself. Documents and flows are two kinds of thing that share one tree
 // (ADR-0004 §1), so the graph carries both and says which of them it is.

package/dist/contract/share.d.ts

@@ -20,6 +20,10 @@ export declare const ListGrantsInput: z.ZodObject<{
     resourceId: z.ZodString;
 }, z.core.$strict>;
 export type ListGrantsInput = z.infer<typeof ListGrantsInput>;
+export declare const ListFlowGrantsInput: z.ZodObject<{
+    flowId: z.ZodString;
+}, z.core.$strict>;
+export type ListFlowGrantsInput = z.infer<typeof ListFlowGrantsInput>;
 export declare const ResourceGrant: z.ZodObject<{
     id: z.ZodString;
     resourceId: z.ZodString;
@@ -70,6 +74,33 @@ export declare const RevokeGrantInput: z.ZodObject<{
     idempotencyKey: z.ZodString;
 }, z.core.$strict>;
 export type RevokeGrantInput = z.infer<typeof RevokeGrantInput>;
+export declare const ShareFlowInput: z.ZodObject<{
+    flowId: z.ZodString;
+    principal: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"user">;
+        id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"email">;
+        email: z.ZodEmail;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"organization">;
+    }, z.core.$strict>], "type">;
+    verb: z.ZodEnum<{
+        read: "read";
+        write: "write";
+        execute: "execute";
+        share: "share";
+    }>;
+    expiresAt: z.ZodDefault<z.ZodNullable<z.ZodISODateTime>>;
+    idempotencyKey: z.ZodString;
+}, z.core.$strict>;
+export type ShareFlowInput = z.infer<typeof ShareFlowInput>;
+export declare const RevokeFlowGrantInput: z.ZodObject<{
+    flowId: z.ZodString;
+    grantId: z.ZodString;
+    idempotencyKey: z.ZodString;
+}, z.core.$strict>;
+export type RevokeFlowGrantInput = z.infer<typeof RevokeFlowGrantInput>;
 export declare const UnreadableNodes: z.ZodObject<{
     titles: z.ZodArray<z.ZodString>;
     hidden: z.ZodNumber;
@@ -102,6 +133,10 @@ export declare const ShareResult: z.ZodObject<{
         titles: z.ZodArray<z.ZodString>;
         hidden: z.ZodNumber;
     }, z.core.$strict>;
+    unrunnable: z.ZodDefault<z.ZodObject<{
+        titles: z.ZodArray<z.ZodString>;
+        hidden: z.ZodNumber;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export type ShareResult = z.infer<typeof ShareResult>;
 export declare const ResourceGrantList: z.ZodObject<{

package/dist/contract/share.js

@@ -17,6 +17,12 @@ export const SharePrincipal = z.discriminatedUnion("type", [
 export const ListGrantsInput = z.strictObject({
     resourceId: IntelId.describe("Node whose direct grants to list. Access inherited from a folder above is not a grant on this node and is not listed here."),
 });
+// The same three shapes for a flow (#530). Separate inputs rather than a widened `resourceId`,
+// because the id names a different table and a caller that passes the wrong kind should be told so
+// by the route it called rather than by a lookup that finds nothing.
+export const ListFlowGrantsInput = z.strictObject({
+    flowId: IntelId.describe("Flow whose direct grants to list. Access inherited from the folder it is filed in is not a grant on this flow and is not listed here."),
+});
 export const ResourceGrant = z.strictObject({
     id: IntelId,
     resourceId: IntelId,
@@ -40,6 +46,20 @@ export const RevokeGrantInput = z.strictObject({
     grantId: IntelId.describe("The grant to withdraw, from node_grant_list."),
     idempotencyKey: IdempotencyKey,
 });
+export const ShareFlowInput = z.strictObject({
+    flowId: IntelId.describe("Flow to grant access to. A grant here reaches this flow and nothing else — not the folder it is filed in, and not the flows it calls."),
+    principal: SharePrincipal.describe("Who gets the access: a Gate user by id, someone by verified email address, or the whole organization."),
+    verb: ResourceVerb.describe("What they may do. Each verb is granted on its own and none implies another: `read` opens the flow, `write` edits it, `execute` runs it, `share` passes access on."),
+    expiresAt: IsoDateTime.nullable()
+        .default(null)
+        .describe("When the grant stops working, or `null` for one that does not expire on its own."),
+    idempotencyKey: IdempotencyKey,
+});
+export const RevokeFlowGrantInput = z.strictObject({
+    flowId: IntelId.describe("Flow the grant sits on. Named alongside the grant id so access is decided on the flow."),
+    grantId: IntelId.describe("The grant to withdraw, from flow_grant_list."),
+    idempotencyKey: IdempotencyKey,
+});
 // What a grant does not cover, reported to whoever just made it. A flow in the shared folder may
 // read a document outside it, and the run is re-authorized against the person running it — so the
 // grant can be complete and the flow still stop for them (ADR-0004 §4).
@@ -53,9 +73,17 @@ export const UnreadableNodes = z.strictObject({
 // The grant is in the answer, so the warning cannot be mistaken for a refusal: it is written first
 // and described afterwards. Blocking would force everyone who uses a central policy document to
 // duplicate it, which is the opposite of what one tree is for (ADR-0004 §4).
+//
+// ⚠️ `unrunnable` is the second half of the same sentence and belongs to the flow grant (#530). A
+// grant on a folder covered every flow beneath it, so there was nothing to say; a grant on one flow
+// reaches that flow and stops, and the sub-flows it calls are then somebody else's to grant. It
+// carries the shape of `UnreadableNodes` because it answers the same question — what this grant
+// does NOT reach, named where the sharer may see it and counted where they may not — and it is
+// empty for every node grant.
 export const ShareResult = z.strictObject({
     grant: ResourceGrant,
     unreadable: UnreadableNodes,
+    unrunnable: UnreadableNodes.default({ titles: [], hidden: 0 }),
 });
 // `applicableVerbs` travels with the list because the answer is the business layer's, not the
 // screen's: a document has nothing to execute, so `execute` is not offered on one (ADR-0004 §2).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-contract",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {