@google-cloud/kcmd 0.0.0-stage → 0.1.0

package/build/ts/kcmd/semantic/runtime/store.js

@@ -0,0 +1,344 @@
+"use strict";
+// The store a model's data lives in.
+//
+// A deployment that uses a binding profile names a target; this module turns
+// that declaration into structured store coordinates. A profile may deploy to
+// Spanner, to AlloyDB or to BigQuery. `kind` is the discriminant, and what
+// differs by it is how the store is ADDRESSED -- the coordinates it takes and
+// the dialect it speaks -- not whether an action may write to it.
+//
+// All three execute SQL DML, so all three can be the store a model's actions
+// run against. BigQuery is a warehouse rather than a transactional database
+// and a write there costs what a warehouse write costs, but that is a question
+// about the model an author is building, not a rule this module enforces.
+//
+// Identity is `name`, the resource the store addresses. Two profiles naming
+// the same database describe ONE store; the profile is how a caller found it,
+// not what it is.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveStore = resolveStore;
+exports.profileTargets = profileTargets;
+exports.withPrimaryInstance = withPrimaryInstance;
+exports.storeLine = storeLine;
+const deployment_target_1 = require("../deployment_target");
+const loader_1 = require("../loader");
+const resolve_profiles_1 = require("../resolve_profiles");
+// A BigQuery table an entity is bound to. The loader rewrites the resource-name
+// URI an author may write into `project.dataset.table`, which is the form the
+// generator emits and the only one that reaches here. The table name takes any
+// character the loader allows in one, which is anything but a dot or a slash,
+// so a name with `$` or a letter outside ASCII is still a table here.
+const BIGQUERY_TABLE_SOURCE = /^([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]+)\.[^./]+$/;
+// The database a bound table sits in, or undefined when the source names no
+// table of any backend this module knows. A Spanner or AlloyDB source, in
+// either spelling, takes the loader's databaseOf form, `spanner/<p>/<i>/<db>`
+// or `alloydb/<p>/<l>/<c>/<db>`.
+function storeOf(source) {
+    const database = (0, loader_1.databaseOf)(source);
+    if (database?.startsWith('spanner/') || database?.startsWith('alloydb/')) {
+        return database;
+    }
+    const bigQuery = source.match(BIGQUERY_TABLE_SOURCE);
+    if (bigQuery)
+        return `bigquery/${bigQuery[1]}/${bigQuery[2]}`;
+    return undefined;
+}
+// Every table the model binds, not just its entities: a many-to-many
+// relationship is backed by a junction table of its own, and an action that
+// creates the edge writes to exactly that one.
+function boundTables(model) {
+    const bindings = [];
+    for (const entity of model.entities ?? []) {
+        bindings.push({
+            name: entity.name,
+            source: entity.dataSource ?? '',
+            shown: (0, loader_1.writtenSource)(entity),
+        });
+    }
+    for (const relationship of model.relationships ?? []) {
+        const source = relationship.association?.dataSource;
+        if (source) {
+            bindings.push({ name: relationship.name, source, shown: (0, loader_1.asResourceName)(source) });
+        }
+    }
+    return bindings;
+}
+// The database a store addresses, in the form storeOf gives. An AlloyDB
+// store matches a source on project, location, cluster and database.
+function storeDatabase(store) {
+    switch (store.kind) {
+        case 'spanner':
+            return `spanner/${store.project}/${store.instance}/${store.database}`;
+        case 'alloydb':
+            return `alloydb/${store.project}/${store.location}/${store.cluster}/${store.database}`;
+        case 'bigquery':
+            return `bigquery/${store.project}/${store.dataset}`;
+    }
+}
+// Bindings that address something other than the store the deployment target
+// names. An action's statements address a table by its NAME, with the
+// project/instance/database qualifier dropped, so an entity bound elsewhere
+// would produce a statement against whatever table of that name the target
+// store happens to hold.
+function strayBindings(model, store) {
+    const database = storeDatabase(store);
+    const strays = [];
+    for (const binding of boundTables(model)) {
+        const source = binding.source.trim();
+        if (!source)
+            continue;
+        const bound = storeOf(source);
+        if (!bound) {
+            strays.push(`'${binding.name}' to ${binding.shown}, which is not a table in this store`);
+            continue;
+        }
+        if (bound !== database)
+            strays.push(`'${binding.name}' to ${binding.shown}`);
+    }
+    return strays;
+}
+/**
+ * The store a model runs against under binding profile `profile`, which
+ * defaults to `default`, the model file's own bindings. It is the one the
+ * deployments for that profile name: those that name it in `profile`, or that
+ * name none or `default` for `default`. A model with no `deployments` list
+ * names no profile for any of its targets, so they are all for `default`.
+ * With several targets, the store is the single operational one, Spanner or
+ * AlloyDB.
+ *
+ * Fails six ways:
+ *
+ * 1. A GOOGLE block's data is not valid JSON, so its targets cannot be read.
+ * 2. A target names no supported destination. Push checks the target of every
+ *    deployment, so this fails the store under every profile.
+ * 3. No deployment uses the profile.
+ * 4. There are several targets and no single operational one, so which store
+ *    is meant is ambiguous.
+ * 5. There is no target, so there is nothing to run against.
+ * 6. The model binds a table outside the store. For a Spanner or AlloyDB
+ *    store, a write would land in the wrong place, and the error is named. A
+ *    BigQuery graph may read tables in any dataset, so
+ *    for a BigQuery store the error is not named.
+ */
+function resolveStore(model, profile = resolve_profiles_1.DEFAULT_PROFILE) {
+    // Push checks the target of every deployment the model declares, so the
+    // targets of every deployment are read before the profile's are picked.
+    let all;
+    try {
+        all = (0, deployment_target_1.googleDeploymentTargets)(model);
+    }
+    catch (err) {
+        // It throws when a GOOGLE block's data is not valid JSON. Push reports
+        // that as an error, so the store fails.
+        return { error: `${err?.message || err}`, named: true, rejected: true };
+    }
+    // The loader reads a vanilla model's `deployments` out of its GOOGLE block,
+    // so a message names the block's `deployments`, as push does.
+    const vanilla = model.version === loader_1.OSSIE_VERSION;
+    const where = vanilla && model.deployments ?
+        `its GOOGLE block's 'deployments'` :
+        `'deployments'`;
+    // A target in no accepted form is reported, alone or beside one that gives
+    // a store, whichever profile its deployment is for.
+    if (all.malformed.length) {
+        const unparsed = model.deployments?.find(d => d.target === all.malformed[0]);
+        const error = unparsed ? (0, deployment_target_1.deploymentTargetError)(model, unparsed) :
+            (0, deployment_target_1.googleBlockTargetError)(model, all.malformed[0]);
+        return { error, named: true, rejected: true };
+    }
+    const used = deploymentsFor(model, profile);
+    if ('error' in used)
+        return used;
+    const scoped = used.model;
+    // The profile's targets are among those read above. So this does not
+    // throw, and none of them is in no accepted form.
+    const targets = (0, deployment_target_1.googleDeploymentTargets)(scoped);
+    const { spanner, alloyDb, bigQuery } = targets;
+    const declared = spanner.length + alloyDb.length + bigQuery.length;
+    const operational = [...spanner, ...alloyDb];
+    const contenders = operational.length ? operational : bigQuery;
+    if (contenders.length > 1) {
+        const counted = [
+            ...(spanner.length ? [`${spanner.length} Spanner`] : []),
+            ...(alloyDb.length ? [`${alloyDb.length} AlloyDB`] : []),
+            ...(operational.length ? [] : [`${bigQuery.length} BigQuery`]),
+        ];
+        const what = counted.length > 1 ?
+            `deployment targets on two operational backends (${counted.join(' and ')})` :
+            `${counted[0]} deployment targets`;
+        const names = deploymentNames(scoped, contenders.map(t => t.uri), profile);
+        return {
+            error: `Model '${model.name}' declares ${what} in ${where}${names}, so which store it runs against is ambiguous; the ` +
+                `runtime uses exactly one deployment for now.`,
+            named: true,
+            rejected: true,
+        };
+    }
+    if (!declared) {
+        const declare = vanilla ?
+            ` In a GOOGLE custom_extensions block on the model, declare a ` +
+                `deployment in 'deployments' whose target names a database.` :
+            ` Declare a deployment in 'deployments' whose target names a ` +
+                `database.`;
+        return {
+            error: `Model '${model.name}' declares no deployment target in ${where}, so there is no store to run against.${declare}`,
+        };
+    }
+    const store = storeFor(spanner[0], alloyDb[0], bigQuery[0]);
+    const strays = strayBindings(model, store);
+    if (strays.length) {
+        return {
+            error: `Model '${model.name}' binds ${strays.join(', ')}, but its ` +
+                `deployment target is ${store.name}. An action's statements ` +
+                `address a table by name alone, so the write would land in the ` +
+                `target store's table of that name rather than in the bound one. ` +
+                `Bind both to the same store.`,
+            // A BigQuery graph may read tables in any dataset, BigLake included,
+            // so the model then has no store, and a caller
+            // does not fail.
+            ...(store.kind === 'bigquery' ? {} : { named: true }),
+        };
+    }
+    return store;
+}
+// The model with only the deployments `profile` uses, or why there are none.
+// A model with no `deployments` list keeps every target in its GOOGLE block
+// for `default`. An empty list names no deployment. Either way, any other
+// profile has none.
+function deploymentsFor(model, profile) {
+    const nothingToRun = `so there is no database to run it against`;
+    const namedProfile = `binding profile '${profile}' is a named profile, ` +
+        `which names no deployment target`;
+    if (!model.deployments?.length) {
+        return profile === resolve_profiles_1.DEFAULT_PROFILE ?
+            { model } :
+            { error: `${namedProfile}, ${nothingToRun}` };
+    }
+    const used = model.deployments.filter(d => (d.profile ?? resolve_profiles_1.DEFAULT_PROFILE) === profile);
+    if (!used.length) {
+        // A vanilla model lists its deployments in its GOOGLE block.
+        const listed = model.version === loader_1.OSSIE_VERSION ?
+            `its GOOGLE block's 'deployments'` :
+            `'deployments'`;
+        let error;
+        if (profile === resolve_profiles_1.DEFAULT_PROFILE) {
+            error = `Model '${model.name}' declares no deployment without a ` +
+                `'profile' in ${listed}, so there is no store to run against ` +
+                `under binding profile '${resolve_profiles_1.DEFAULT_PROFILE}'.`;
+        }
+        else {
+            error = `${namedProfile}, and no deployment in ${listed} uses it, ${nothingToRun}`;
+        }
+        return { error };
+    }
+    return { model: { ...model, deployments: used } };
+}
+/**
+ * The targets binding profile `profile` uses, as resolveStore reads them: its
+ * deployments' targets, or every target in a GOOGLE block for `default` when
+ * the model has no `deployments` list. Empty when no deployment is for the
+ * profile. Throws when a GOOGLE block's data is not valid JSON.
+ */
+function profileTargets(model, profile) {
+    const used = deploymentsFor(model, profile);
+    return 'error' in used ? [] : (0, deployment_target_1.googleDeploymentTargets)(used.model).uris;
+}
+// The deployments whose targets are `uris`, for a message, or nothing when
+// the targets come from a GOOGLE block, which names none. `profile` is the
+// profile they are for.
+function deploymentNames(model, uris, profile) {
+    const deployments = model.deployments;
+    if (!deployments)
+        return '';
+    const names = uris.map(uri => deployments.find(d => d.target === uri)?.name ?? uri);
+    return ` for profile '${profile}' (${names.join(', ')})`;
+}
+function storeFor(spanner, alloyDb, bigQuery) {
+    if (spanner) {
+        return {
+            kind: 'spanner',
+            name: `projects/${spanner.project}/instances/${spanner.instance}/databases/${spanner.database}`,
+            project: spanner.project,
+            instance: spanner.instance,
+            database: spanner.database,
+        };
+    }
+    if (alloyDb) {
+        return {
+            kind: 'alloydb',
+            name: `projects/${alloyDb.project}/locations/${alloyDb.location}/clusters/${alloyDb.cluster}/databases/${alloyDb.database}`,
+            project: alloyDb.project,
+            location: alloyDb.location,
+            cluster: alloyDb.cluster,
+            database: alloyDb.database,
+        };
+    }
+    return {
+        kind: 'bigquery',
+        name: `projects/${bigQuery.project}/datasets/${bigQuery.dataset}`,
+        project: bigQuery.project,
+        dataset: bigQuery.dataset,
+    };
+}
+/**
+ * `store` with the instance a connection goes through. An AlloyDB target
+ * names a database in a cluster, so this asks the AlloyDB API for the
+ * cluster's primary instance. Fails, naming the cluster, when it has none,
+ * when the primary is not READY, or when the listing fails. Any other store
+ * comes back unchanged.
+ */
+async function withPrimaryInstance(store, client) {
+    if (store.kind !== 'alloydb')
+        return store;
+    const cluster = `projects/${store.project}/locations/${store.location}/clusters/${store.cluster}`;
+    let res;
+    try {
+        res = await client.listInstances(store.project, store.location, store.cluster);
+    }
+    catch (err) {
+        return {
+            error: `Could not list the instances of AlloyDB cluster '${cluster}': ${err?.message ?? err}`,
+        };
+    }
+    if (res.status !== 200) {
+        return {
+            error: `Could not list the instances of AlloyDB cluster '${cluster}': ${apiError(res)}`,
+        };
+    }
+    const primary = res.result?.find(i => i.instanceType === 'PRIMARY');
+    const instance = primary?.name?.split('/').pop();
+    if (!primary || !instance) {
+        return {
+            error: `AlloyDB cluster '${cluster}' has no primary instance, so there ` +
+                `is no instance to connect to database '${store.database}' through.`,
+        };
+    }
+    if (primary.state !== 'READY') {
+        return {
+            error: `AlloyDB cluster '${cluster}' has primary instance '${instance}' in state ${primary.state ?? 'STATE_UNSPECIFIED'}; it ` +
+                `must be READY to connect to database '${store.database}' through it.`,
+        };
+    }
+    return { ...store, instance };
+}
+// The message of a failed API call, after the HTTP status.
+function apiError(res) {
+    const message = res.message?.trim();
+    return message ? `${res.status} ${message}` : `${res.status}`;
+}
+/**
+ * How a store is written down for a reader: the resource it addresses, with
+ * the backend named ahead of it for everything but Spanner, which is the one
+ * an unprefixed line has always meant.
+ */
+function storeLine(store) {
+    switch (store.kind) {
+        case 'spanner':
+            return `${store.project}/${store.instance}/${store.database}`;
+        case 'alloydb':
+            return `alloydb:${store.project}/${store.location}/${store.cluster}/` +
+                `${store.instance}/${store.database}`;
+        case 'bigquery':
+            return `bigquery:${store.project}/${store.dataset}`;
+    }
+}

package/build/ts/kcmd/semantic/skills.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Generating an Agent Skill from a semantic model.
+ *
+ * An Agent Skill (agentskills.io) is a directory holding a `SKILL.md` -- YAML
+ * frontmatter naming the skill, then Markdown telling an agent how to do
+ * something. Clients load the frontmatter at startup and the body only when
+ * the skill looks relevant, so the body has a budget: under 500 lines, and
+ * under about 5,000 tokens. Anything longer goes in files the body points at,
+ * which the agent reads only if it needs them.
+ *
+ * That budget decides the shape of what this emits. A model's actions carry
+ * their parameters, the rules that gate them and the blast radius of each
+ * call, and inlining all of it puts a page of detail about every action in
+ * front of an agent that wanted one of them. So `SKILL.md` is a ROUTER: what
+ * the model is, a one-line table of the actions, and the parts that are true
+ * of every call. Each action's detail is a file under `references/`, named in
+ * the table, read on demand. A model with thirty actions costs the same at
+ * startup as a model with one.
+ *
+ * Nothing here decides what an action means. `modelTools` already turns a
+ * bound model into the action descriptors a skill needs -- the tool name, the
+ * description with the gating rules folded in, the typed parameters, and
+ * whether this binding can run it -- so this module renders what `modelTools`
+ * returns and derives nothing of its own beyond layout.
+ *
+ * The skill is written against the LOGICAL model, which is what makes it worth
+ * generating once. An action's name, arguments, rules and blast radius are the
+ * same wherever it is deployed, because an executor is a physical binding that
+ * a profile supplies. So every `references/` page is a fact about the model
+ * and nothing else, and everything that reads the binding lives in `SKILL.md`:
+ * the store, the executor kinds, which actions this deployment cannot run and
+ * why, and the command line to try one with, all gathered under "Running an
+ * action", plus the snippet under "Finding a record" that reads the store
+ * directly, which needs the store's kind and its coordinates. Point this at a
+ * different profile and those move and the reference pages do not.
+ *
+ * Keeping that true takes some discipline: whether an action is RUNNABLE is a
+ * binding fact wearing a logical name, and putting `tool.unavailable` on the
+ * action's own page -- which reads naturally, and which this module did at
+ * first -- quietly makes every page profile-specific.
+ */
+import { SemanticRuntime } from './runtime/runtime';
+/** One file of the generated package, at a path relative to the skill root. */
+export interface SkillFile {
+    /** Relative to the skill directory, POSIX-separated. `SKILL.md` is first. */
+    path: string;
+    text: string;
+}
+/** A generated skill: the directory name it must be written under, and why. */
+export interface SkillPackage {
+    /**
+     * The skill's name, which is also the directory name it must be written
+     * under. The two are required to match, so they come from one place.
+     */
+    name: string;
+    files: SkillFile[];
+    /**
+     * What a reader should know about the skill that was generated -- a body
+     * over its budget, a model that declares nothing to act on. Not errors:
+     * every one of them still produces a skill, and the caller decides whether
+     * it is the skill it wanted.
+     */
+    warnings: string[];
+}
+export interface GenerateSkillOptions {
+    /** The model to describe, under the binding profile it was read with. */
+    runtime: SemanticRuntime;
+    /**
+     * The skill's name, defaulting to the model's own in the form the spec
+     * requires. Validated either way: a name the spec rejects is an error here
+     * rather than a skill some clients silently skip.
+     */
+    name?: string;
+}
+/**
+ * The skill for one model, as files a caller writes out.
+ *
+ * Returns an error for a name the Agent Skills spec would reject. It also
+ * returns the store error when the model's deployments are rejected, and
+ * when the profile names a store that cannot be resolved for a model with
+ * actions, whose skill names the store. A model with no actions is not an
+ * error -- it is a skill that says the model declares nothing to act on, which
+ * is the honest thing to hand an agent -- but it is warned about, because it
+ * is rarely what the caller meant.
+ */
+export declare function generateSkill(opts: GenerateSkillOptions): SkillPackage | {
+    error: string;
+};
+/**
+ * A model name in the form the spec requires: 1-64 characters of lowercase
+ * `a-z0-9-`, with no leading, trailing or doubled hyphen.
+ *
+ * `Commerce` and `commerce_demo` are both ordinary model names and neither is
+ * a legal skill name, so this is a conversion rather than a check. What it
+ * cannot fix -- a name with no alphanumeric character in it at all -- falls
+ * through to the validator, which says so.
+ */
+export declare function skillNameFor(modelName: string): string;
+/**
+ * Why this name is not a legal skill name, or undefined if it is.
+ *
+ * Worth being strict about here rather than leaving to the client. A skill
+ * whose `name` does not match its directory is loaded by a lenient client and
+ * SKIPPED by a strict one -- the Agent Plugins spec requires a client to skip
+ * a non-conformant skill -- so the failure shows up as a skill that quietly
+ * does nothing on somebody else's machine. This generator names the directory
+ * from the same string it writes into the frontmatter, so the pair cannot
+ * disagree; the rest is the character rules.
+ */
+export declare function whyNameIsInvalid(name: string): string | undefined;