@sixb/cli-core 0.1.8 → 0.1.9

package/dist/output.d.ts

@@ -2,6 +2,8 @@
 export declare const INSTANCE_CLI_VERSION = "1";
 export declare const EXIT_USAGE = 2;
 export declare const EXIT_API = 3;
+/** The request waits for its user's approval: it did not run. */
+export declare const EXIT_AWAITING_APPROVAL = 4;
 export interface CliErrorBody {
     readonly code: string;
     readonly status?: number;
@@ -16,6 +18,16 @@ export declare class CliError extends Error {
 }
 export declare function fail(message: string, code?: string, hint?: string): never;
 export declare function writeJson(value: unknown): void;
+/** Ends a command that already wrote its output, with an exit code that is not a success. */
+export declare class CliExit extends Error {
+    readonly exitCode: number;
+    constructor(exitCode: number);
+}
+/**
+ * Print what a request that changes state answered. A request held for the user's approval prints
+ * as the API answered it, and exits with {@link EXIT_AWAITING_APPROVAL}: `a && b` does not run `b`.
+ */
+export declare function writeRequestResult(value: unknown): void;
 export declare function writeText(value: string): void;
 export declare function reportError(error: unknown): number;
 //# sourceMappingURL=output.d.ts.map

package/dist/output.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,eAAO,MAAM,oBAAoB,MAAM,CAAA;AACvC,eAAO,MAAM,UAAU,IAAI,CAAA;AAC3B,eAAO,MAAM,QAAQ,IAAI,CAAA;AAEzB,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,CAAA;CACrC;AAED,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;gBAEb,IAAI,EAAE,YAAY,EAAE,QAAQ,SAAa;CAMtD;AAED,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,SAAsB,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,CAEtF;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAE9C;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAalD"}
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,eAAO,MAAM,oBAAoB,MAAM,CAAA;AACvC,eAAO,MAAM,UAAU,IAAI,CAAA;AAC3B,eAAO,MAAM,QAAQ,IAAI,CAAA;AACzB,iEAAiE;AACjE,eAAO,MAAM,sBAAsB,IAAI,CAAA;AAEvC,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,CAAA;CACrC;AAED,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;gBAEb,IAAI,EAAE,YAAY,EAAE,QAAQ,SAAa;CAMtD;AAED,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,SAAsB,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,CAEtF;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAE9C;AAED,6FAA6F;AAC7F,qBAAa,OAAQ,SAAQ,KAAK;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM;gBAAhB,QAAQ,EAAE,MAAM;CAItC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAIvD;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAclD"}

package/dist/policies.d.ts

@@ -20,6 +20,11 @@ export declare const CLI_LIMITS: {
         readonly default: 100;
         readonly maximum: 1000;
     };
+    /** The server lists at most 200 members per page. */
+    readonly users: {
+        readonly default: 20;
+        readonly maximum: 200;
+    };
     readonly inspect: {
         readonly depth: {
             readonly default: 2;

package/dist/policies.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"policies.d.ts","sourceRoot":"","sources":["../src/policies.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,eAAO,MAAM,UAAU;;;;;;;;;IAGrB,+FAA+F;;;;;;;;;;;;;;;;;;;;;;;;;;;CAUvF,CAAA;AAEV,eAAO,MAAM,kBAAkB,EAAG,MAAe,CAAA;AACjD,eAAO,MAAM,uBAAuB,EAAG,WAAoB,CAAA;AAC3D,eAAO,MAAM,uBAAuB,EAAG,MAAe,CAAA"}
+{"version":3,"file":"policies.d.ts","sourceRoot":"","sources":["../src/policies.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,eAAO,MAAM,UAAU;;;;;;;;;IAGrB,+FAA+F;;;;;;;;;;;;IAI/F,qDAAqD;;;;;;;;;;;;;;;;;;;;CAQ7C,CAAA;AAEV,eAAO,MAAM,kBAAkB,EAAG,MAAe,CAAA;AACjD,eAAO,MAAM,uBAAuB,EAAG,WAAoB,CAAA;AAC3D,eAAO,MAAM,uBAAuB,EAAG,MAAe,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sixb/cli-core",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Shared instance command runtime for Sixb CLIs",
   "keywords": [
     "sixb",

package/src/api-client.ts

@@ -41,9 +41,20 @@ export class ApiClient {
     })
   }
 
-  async upload(path: string, source: string, logicalPath?: string): Promise<unknown> {
+  /** `mediaType` labels the part; without it, the server reads the type from the file name. */
+  async upload(
+    path: string,
+    source: string,
+    logicalPath?: string,
+    mediaType?: string
+  ): Promise<unknown> {
     const form = new FormData()
-    form.append("file", new Blob([new Uint8Array(await readFile(source))]), basename(source))
+    const bytes = new Uint8Array(await readFile(source))
+    form.append(
+      "file",
+      new Blob([bytes], mediaType ? { type: mediaType } : undefined),
+      basename(source)
+    )
     if (logicalPath) form.append("logicalPath", logicalPath)
     return this.json(this.url(path), { method: "POST", body: form })
   }

package/src/arguments.ts

@@ -1,6 +1,13 @@
 import { fail } from "./output"
 
-type OptionKinds = Readonly<Record<string, "string" | "boolean">>
+/** `strings` may repeat, and collects every value in order. */
+type OptionKinds = Readonly<Record<string, "string" | "strings" | "boolean">>
+
+type OptionValue<TKind> = TKind extends "boolean"
+  ? boolean
+  : TKind extends "strings"
+    ? string[]
+    : string
 
 /** Parse a command's options once, before reading files or calling the API. */
 export function parseCommandArgs<const T extends OptionKinds>(
@@ -10,10 +17,10 @@ export function parseCommandArgs<const T extends OptionKinds>(
   positionalCount: number | readonly [number, number] = 0
 ): {
   positionals: string[]
-  options: { [K in keyof T]?: T[K] extends "boolean" ? boolean : string }
+  options: { [K in keyof T]?: OptionValue<T[K]> }
 } {
   const positionals: string[] = []
-  const options: Record<string, string | boolean> = {}
+  const options: Record<string, string | string[] | boolean> = {}
   let positionalOnly = false
   for (let index = 0; index < args.length; index++) {
     const argument = args[index] ?? ""
@@ -28,7 +35,9 @@ export function parseCommandArgs<const T extends OptionKinds>(
     const equals = argument.indexOf("=")
     const flag = equals < 0 ? argument : argument.slice(0, equals)
     if (!Object.hasOwn(kinds, flag)) fail(`Unknown ${command} option '${flag}'.`)
-    if (Object.hasOwn(options, flag)) fail(`${flag} may only be provided once.`)
+    if (Object.hasOwn(options, flag) && kinds[flag] !== "strings") {
+      fail(`${flag} may only be provided once.`)
+    }
     if (kinds[flag] === "boolean") {
       if (equals >= 0) fail(`${flag} does not accept a value.`)
       options[flag] = true
@@ -37,7 +46,9 @@ export function parseCommandArgs<const T extends OptionKinds>(
       if (!value || (equals < 0 && value.startsWith("--"))) {
         fail(`${flag} requires a value.`)
       }
-      options[flag] = value
+      const previous = options[flag]
+      options[flag] =
+        kinds[flag] === "strings" ? [...(Array.isArray(previous) ? previous : []), value] : value
     }
   }
   const [minimum, maximum] =
@@ -48,7 +59,7 @@ export function parseCommandArgs<const T extends OptionKinds>(
   return {
     positionals,
     // Every assigned option was checked against its declared kind above.
-    options: options as { [K in keyof T]?: T[K] extends "boolean" ? boolean : string },
+    options: options as { [K in keyof T]?: OptionValue<T[K]> },
   }
 }
 

package/src/commands/actions.ts

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto"
 import type { ApiClient } from "../api-client"
 import { isHelp, parseCommandArgs, requestsHelp } from "../arguments"
-import { CliError, EXIT_API, fail, writeJson, writeText } from "../output"
+import { CliError, EXIT_API, fail, writeJson, writeRequestResult, writeText } from "../output"
 import { GROUP_HELP } from "./metadata"
 import { asRecord, parseQueryOptions, readJson } from "./shared"
 
@@ -62,7 +62,7 @@ export async function actions(
     const requestedRunId = runId ?? `act_${randomUUID()}`
     const waiting = AbortSignal.timeout(requestWaitMs)
     try {
-      return writeJson(
+      return writeRequestResult(
         await api.post(
           `/api/actions/${encodeURIComponent(actionId)}`,
           {

package/src/commands/index.ts

@@ -2,11 +2,13 @@ import type { ApiClient } from "../api-client"
 import { fail } from "../output"
 import { actions } from "./actions"
 import { files } from "./files"
+import { models } from "./models"
 import { objects } from "./objects"
 import { ontology } from "./ontology"
 import { project } from "./project"
 import { runs } from "./runs"
 import { telemetry } from "./telemetry"
+import { users } from "./users"
 import { workflows } from "./workflows"
 
 export const INSTANCE_COMMANDS = [
@@ -19,6 +21,8 @@ export const INSTANCE_COMMANDS = [
   "files",
   "workflows",
   "workflow-runs",
+  "users",
+  "models",
 ] as const
 
 export type InstanceCommand = (typeof INSTANCE_COMMANDS)[number]
@@ -51,6 +55,10 @@ export async function dispatch(
       return workflows(api, args)
     case "workflow-runs":
       return runs(api, "workflow", args)
+    case "users":
+      return users(api, args)
+    case "models":
+      return models(api, args)
     default:
       fail(`Unknown command '${command}'. Run 'sixb --help'.`)
   }

package/src/commands/metadata.ts

@@ -28,6 +28,8 @@ Objects:
   sixb objects inspect <type> <id>    Inspect an object and its related graph in one command
   sixb objects list [options]         Browse materialized objects
   sixb objects get <type> <id>...     Exact lookup through opaque object references
+  sixb objects get-by <type> <property> <value>
+                                      The object holding a value of a unique property
   sixb objects search <text>          Search visible objects by id prefix and full text
   sixb objects search <text> --type <type>
                                       Semantic search through the type's vector profile
@@ -51,6 +53,13 @@ Actions and workflows:
 Files:
   sixb files upload|download ...
 
+Members:
+  sixb users search <text>            Find members by name or email
+  sixb users list|get ...
+
+A user parameter or property is {"type":"user","id":"<user-id>"}. Find the id with
+\`sixb users search <name>\`.
+
 Run \`sixb <group> --help\` or \`sixb <group> <command> --help\` for exact arguments.
 For query IR, run \`sixb objects query --help\` and \`sixb objects query --example list\`.`
 
@@ -68,6 +77,12 @@ const LOCAL_MAIN_HELP = SANDBOX_MAIN_HELP.replace("Sixb agent CLI", "Sixb instan
     ""
   )
 
+  // The agent reaches models through its run's gateway once the model routes allow it.
+  .replace(
+    "Files:\n  sixb files upload|download ...\n",
+    "Files:\n  sixb files upload|download ...\n\nModels:\n  sixb models list [--kind <kind>]    Configured models of every kind, with prices\n  sixb models get <model>             One model's options and rate card\n  sixb models text|image|speech|transcribe ...   Call a model; see sixb models --help\n"
+  )
+
 export function renderInstanceHelp(mode: "local" | "sandbox"): string {
   return mode === "sandbox" ? SANDBOX_MAIN_HELP : LOCAL_MAIN_HELP
 }
@@ -87,10 +102,19 @@ profiles.
 
 ${SEARCH_DETAILS}`
 
+export const GET_BY_HELP = `Usage:
+  sixb objects get-by <object-type> <property> <value> [--json]
+
+Prints the object of exactly <object-type> holding <value> for a property marked unique in its
+ontology doc, or null when no visible object holds it. Values match exactly, case included.
+The value is a string; with --json it is parsed as JSON, for an integer (42) or a user
+reference ({"type":"user","id":"usr_1"}).`
+
 export const OBJECTS_HELP = `Usage:
   sixb objects inspect <object-type> <primary-id> [options]
   sixb objects list [options]
   sixb objects get <object-type> <primary-id>...
+  sixb objects get-by <object-type> <property> <value> [--json]
   sixb objects search <text> [--type <object-type> [--vector-profile <name>]] [--limit <n>]
   sixb objects query --file <path|-> [--include-total|--no-total]
   sixb objects query --example <name>
@@ -158,7 +182,7 @@ Query nodes compose through input:
   limit     {"kind":"limit","input":<query>,"limit":${CLI_LIMITS.list.default}}
   page      {"kind":"page","input":<query>,"pageSize":${CLI_LIMITS.list.default},"pageToken":"from nextPageToken"}
   project   {"kind":"project","input":<query>,"properties":["name","status"]}
-  expand    {"kind":"expand","input":<query>,"expansions":[{"linkId":"link","direction":"outgoing","limit":5}]}
+  expand    {"kind":"expand","input":<query>,"expansions":[{"linkId":"link","direction":"outgoing","limit":5}],"users":["assignee"]}
   vector    {"kind":"vector","input":<start|filter>,"vector":"text","profile":"name","k":10}
   rerank    {"kind":"rerank","input":<vector>,"model":{"provider":"provider","modelId":"model"}}
 
@@ -169,11 +193,16 @@ Predicates use op, not kind:
   {"op":"in","propertyId":"status","values":["open","blocked"]}
   {"op":"exists","propertyId":"dueDate","value":true}
   {"op":"contains","propertyId":"tags","value":"urgent"}
+  {"op":"eq","propertyId":"assignee","value":{"type":"currentUser"}}  the caller, on a user reference: neq, in, contains too
 
 Every field shown is required except includeSubtypes, fields, pageToken, properties, a sort
-direction, and an expansion's limit. Sort by relevance after text or vector with
+direction, an expansion's limit, and users. Sort by relevance after text or vector with
 {"kind":"relevance"}. Wrap the outermost node in project to return only the properties you need.
 
+An expand's users, or an expansion's, lists user-reference properties: each row then carries the
+members' profiles under users (id, email, displayName, avatarUrl, status). Without access to the
+member directory, users is empty.
+
 Traversal and expansion directions are outgoing or incoming. For incoming relationships, the link
 is declared on the child/source type; add sourceObjectTypeId when needed to disambiguate it.
 
@@ -209,7 +238,8 @@ History options:
 \`actions get\` includes inputSchema, the exact JSON shape accepted by the Action. The JSON file
 contains that parameter object; use - to read standard input. \`actions request\` runs the Action
 and prints its finished run, with its status and any error. It waits at most 25 seconds: a run that
-takes longer keeps running, and the error names the run to read with \`action-runs get\`.`,
+takes longer keeps running, and the error names the run to read with \`action-runs get\`. A request
+that waits for the user's approval prints \`"status": "awaiting_approval"\` and exits with code 4.`,
   "action-runs": `Usage:
   sixb action-runs list [options]
   sixb action-runs get <run-id>
@@ -230,9 +260,48 @@ List options:
   workflows: `Usage:
   sixb workflows list
   sixb workflows get <workflow-id>
-  sixb workflows start <workflow-id> [--file <path|->]
+  sixb workflows start <workflow-id> [--file <path|->] [--run-id <id>]
+
+The JSON file contains the workflow input object. Use - to read standard input. A start that waits
+for the user's approval prints \`"status": "awaiting_approval"\` and exits with code 4.`,
+  users: `Usage:
+  sixb users list [options]
+  sixb users search <text> [options]
+  sixb users get <user-id>
+
+Options:
+  --status active|suspended|all       Defaults to active
+  --limit <1-${CLI_LIMITS.users.maximum}>                     Defaults to ${CLI_LIMITS.users.default}
+  --offset <n>                        Non-negative; defaults to 0
 
-The JSON file contains the workflow input object. Use - to read standard input.`,
+\`users search\` matches part of a display name or email, ignoring case. Each member is
+{"id","email","displayName","avatarUrl","status"}; a user parameter takes
+{"type":"user","id":"<id>"}. Reading members requires can.view(project.users).`,
+  models: `Usage:
+  sixb models list [--kind language|image|speech|transcription]
+  sixb models get <model> [--kind <kind>]
+  sixb models text "<prompt>"|--file <path|-> [--model <tier|model>] [--instructions <text>]
+                   [--max-output-tokens <n>] [--reasoning <level>]
+  sixb models image "<prompt>" --output <path> [--model <model>] [--n <n>]
+                    [--size <size>] [--aspect-ratio <ratio>] [--quality <q>] [--style <s>]
+                    [--seed <n>] [--image <file>]...
+  sixb models speech "<text>" --output <path> [--model <model>] [--voice <voice>]
+                     [--format mp3|wav|ogg|aac|flac] [--instructions <text>]
+                     [--speed <n>] [--language <code>]
+  sixb models transcribe <file> [--model <model>]
+  sixb models calls files <call-id> [--output <path>]
+
+<model> is a model id, or provider:model-id when two providers share one; without --model, the
+kind's default answers. \`list\` shows each model's kind, default, description and price; \`get\`
+adds the sizes, voices and other options a request can use. Prices are in USD.
+
+\`text\` also takes a tier (light, standard or heavy) for --model, and reads a long prompt from
+--file: a path, or - for standard input.
+
+--output is a file, numbered when a call returns several, or a directory ending in /. The
+extension follows the file's type, and the result lists the paths written. --image uploads a
+reference image; repeat it for several. \`calls files\` lists a past call's files, or downloads
+them again.`,
   "workflow-runs": `Usage:
   sixb workflow-runs list [options]
   sixb workflow-runs get <run-id>
@@ -254,10 +323,12 @@ export const QUERY_EXAMPLES: Readonly<Record<string, string>> = {
   not: `{"kind":"limit","input":{"kind":"filter","input":{"kind":"start","objectTypeId":"Customer"},"predicate":{"op":"not","item":{"op":"eq","propertyId":"status","value":"churned"}}},"limit":${CLI_LIMITS.list.default}}`,
   in: `{"kind":"limit","input":{"kind":"filter","input":{"kind":"start","objectTypeId":"Customer"},"predicate":{"op":"in","propertyId":"status","values":["active","trial"]}},"limit":${CLI_LIMITS.list.default}}`,
   exists: `{"kind":"limit","input":{"kind":"filter","input":{"kind":"start","objectTypeId":"Customer"},"predicate":{"op":"exists","propertyId":"accountManager","value":false}},"limit":${CLI_LIMITS.list.default}}`,
+  mine: `{"kind":"limit","input":{"kind":"filter","input":{"kind":"start","objectTypeId":"Task"},"predicate":{"op":"eq","propertyId":"assignee","value":{"type":"currentUser"}}},"limit":${CLI_LIMITS.list.default}}`,
   project: `{"kind":"project","input":{"kind":"limit","input":{"kind":"start","objectTypeId":"Customer"},"limit":${CLI_LIMITS.list.default}},"properties":["name","status"]}`,
   incoming:
     '{"kind":"traverse","input":{"kind":"refs","refs":[{"objectTypeId":"RepositoryIssue","primaryId":"github:issue:owner/repo#297"}]},"linkId":"issue","direction":"incoming","sourceObjectTypeId":"RepositoryComment"}',
   expand: `{"kind":"expand","input":{"kind":"refs","refs":[{"objectTypeId":"RepositoryIssue","primaryId":"github:issue:owner/repo#297"}]},"expansions":[{"linkId":"issue","direction":"incoming","sourceObjectTypeId":"RepositoryComment","limit":${CLI_LIMITS.list.default}}]}`,
+  users: `{"kind":"expand","input":{"kind":"limit","input":{"kind":"start","objectTypeId":"Task"},"limit":${CLI_LIMITS.list.default}},"expansions":[],"users":["assignee"]}`,
   sort: `{"kind":"limit","input":{"kind":"sort","input":{"kind":"start","objectTypeId":"Customer"},"fields":[{"kind":"property","propertyId":"name","direction":"asc"}]},"limit":${CLI_LIMITS.list.default}}`,
   page: `{"kind":"page","input":{"kind":"start","objectTypeId":"Customer"},"pageSize":${CLI_LIMITS.list.default}}`,
   vector: `{"kind":"vector","input":{"kind":"filter","input":{"kind":"start","objectTypeId":"Product"},"predicate":{"op":"eq","propertyId":"status","value":"active"}},"vector":"waterproof trail shoes","profile":"content","k":${CLI_LIMITS.search.default}}`,