@ibgib/web-gib 0.0.1

package/src/api/commands/chat/get-context-info.mts

@@ -0,0 +1,196 @@
+import { extractErrorMsg, pretty } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+import { IbGibAddr } from "@ibgib/ts-gib/dist/types.mjs";
+import { IbGib_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
+
+import { GLOBAL_LOG_A_LOT } from "../../../constants.mjs";
+import { APIFunctionInfo } from "../../api-types.mjs";
+import { COMMAND_BASE_SCHEMA_PROPERTIES } from "../command-constants.mjs";
+import { getCommandService } from "../command-service-v1.mjs";
+import { CommandDataBase } from "../command-types.mjs";
+import { FUNCTION_CALL_EXAMPLES_HEADER } from "../../api-constants.mjs";
+import { GEMINI_SCHEMA_AGENT_ID, GEMINI_SCHEMA_AGENT_TYPE } from "../../../witness/agent/agent-constants.mjs";
+import { getAgentsSvc } from "../../../witness/agent/agents-service-v1.mjs";
+import { getGlobalMetaspace_waitIfNeeded } from "../../../helpers.web.mjs";
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+// #region constants
+const EXAMPLE_INPUT_GETCONTEXTINFO: Partial<GetContextInfoOpts> = {
+    agentId: 'someidprobablylookslikeahash',
+    agentType: 'sometypehere',
+    notesToSelf: 'Example of a getContextInfo function call. DO NOT USE THESE AS YOUR ACTUAL ARGS. THIS IS ONLY AN EXAMPLE TO SHOW THE SHAPE OF THE FUNCTION CALL!!',
+    repromptWithResult: true,
+};
+
+const EXAMPLES = [
+    // `\`\`\`typescript\n${FUNCTION_CALL_EXAMPLES_HEADER}\n${pretty(EXAMPLE_INPUT_GETCONTEXTINFO)}\n\`\`\``,
+    FUNCTION_CALL_EXAMPLES_HEADER,
+    pretty(EXAMPLE_INPUT_GETCONTEXTINFO),
+].join('\n');
+// #endregion constants
+
+
+/**
+ * @interface CommandResultBase - Base interface for command results.
+ *
+ * ## notes
+ *
+ * I'm adding this after already having created several existing commands in
+ * order to include an errorMsg. I want commands to return info about errors and
+ * not re-throw. I am not integrating this with all existing commands at this
+ * time though, so there will be some irregularity.
+ *
+ * I did go ahead and change the code in the command service to return
+ * `{errorMsg}` if an exception is thrown.
+ */
+export interface CommandResultBase {
+    /**
+     * IIF the command errors out, this will be populated.
+     */
+    errorMsg?: string;
+}
+
+/**
+ * @interface GetContextInfoOpts - Options for the getContextInfo command.
+ * @extends CommandDataBase
+ */
+export interface GetContextInfoOpts extends CommandDataBase<'agent', ['getContextInfo']> {
+    /**
+     * @property agentId - the agent's unique identifier.
+     */
+    agentId: string;
+    /**
+     * @property agentType - type of the agent that corresponds to the basic
+     * responsibilities of the agent
+     */
+    agentType: string;
+}
+
+export interface GetContextInfoResult extends CommandResultBase {
+    contextAddr: IbGibAddr;
+    contextIbGib: IbGib_V1;
+    latestContextAddr?: IbGibAddr;
+    latestContextIbGib?: IbGib_V1;
+}
+
+/**
+ * @interface GetContextInfoCommandData - Command data for the getContextInfo command.
+ * @extends CommandDataBase
+ */
+export interface GetContextInfoCommandData extends CommandDataBase<'agent', ['getContextInfo']> {
+    /**
+     * @property agentId - the agent's unique identifier.
+     */
+    agentId: string;
+    /**
+     * @property agentType - type of the agent that corresponds to the basic
+     * responsibilities of the agent
+     */
+    agentType: string;
+}
+
+/**
+ * Wrapper function to enqueue the getContextInfo command.
+ * @param {GetContextInfoOpts} opts - Options for telling the user something.
+ * @returns {Promise<void>} A promise that resolves when the command is enqueued.
+ */
+function getContextInfoViaCmd(opts: GetContextInfoOpts): Promise<GetContextInfoResult> {
+    const commandService = getCommandService();
+    const command: GetContextInfoCommandData = {
+        cmd: 'agent',
+        cmdModifiers: ['getContextInfo'],
+        agentId: opts.agentId,
+        agentType: opts.agentType,
+        repromptWithResult: opts?.repromptWithResult,
+        notesToSelf: opts?.notesToSelf,
+    };
+    return new Promise<GetContextInfoResult>((resolve, reject) => {
+        commandService.enqueueCommand({ command, resolve, reject });
+    });
+}
+
+/**
+ * Implementation function for the getContextInfo command (atow, does nothing other than resolve).
+ * @param {GetContextInfoOpts} opts - Options for telling the user something.
+ * @returns {Promise<void>} A promise that resolves when the command is executed (immediately).
+ */
+async function getContextInfoImpl(opts: GetContextInfoOpts): Promise<GetContextInfoResult> {
+    const lc = `[${getContextInfoImpl.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: genuuid)`); }
+
+        const { agentId, agentType, } = opts;
+
+        // In the actual implementation, this function might trigger some UI update
+        // or logging, but for now, it's just a placeholder.
+        // debugger; // walk through get-context-info command
+
+        // should get the agent
+        const agentsSvc = getAgentsSvc();
+        const agent = await agentsSvc.getAgentById({ agentId, agentType });
+        if (!agent) { throw new Error(`agent not found for opts: ${pretty(opts)} (E: b0da990f27c85c29e5bf148299507225)`); }
+        if (!agent.data) { throw new Error(`(UNEXPECTED) agent.data is falsy? opts: ${pretty(opts)} (E: a8b357b5c68e5485144e2358d1a60425)`); }
+
+        // get the context info here
+        const metaspace = await getGlobalMetaspace_waitIfNeeded();
+        const contextAddr = agent.data["@currentContextTjpAddr"];
+        const superSpaceId = agent.data.superSpaceId;
+        const superSpace = await metaspace.getLocalUserSpace({ localSpaceId: superSpaceId, lock: false });
+        const resGetContext = await metaspace.get({
+            addrs: [contextAddr],
+            space: superSpace,
+        });
+        if (resGetContext.errorMsg || (resGetContext.ibGibs ?? []).length !== 1) {
+            throw new Error(`couldn't get context ibgib (${contextAddr}) from super space (${superSpaceId}). errorMsg: ${resGetContext.errorMsg ?? '[unknown error]'} (E: 63514d4521e1dc26860354ccbcb02125)`);
+        }
+        const contextIbGib = resGetContext.ibGibs!.at(0)!
+        let latestContextIbGib: IbGib_V1 | undefined = undefined;
+        const latestContextAddr = await metaspace.getLatestAddr({ ibGib: contextIbGib, space: superSpace });
+        if (latestContextAddr) {
+            const resGetLatest = await metaspace.get({
+                addrs: [latestContextAddr], space: superSpace
+            });
+            if (resGetLatest.errorMsg || (resGetLatest.ibGibs ?? []).length !== 1) {
+                throw new Error(`couldn't get latest context ibgib (${latestContextAddr}) from super space (${superSpaceId}). errorMsg: ${resGetLatest.errorMsg ?? '[unknown error]'} (E: 450727cc12e226f8b741dd7b0efbfe25)`);
+            }
+            latestContextIbGib = resGetLatest.ibGibs!.at(0)!;
+        }
+
+        return {
+            contextAddr,
+            contextIbGib,
+            latestContextAddr,
+            latestContextIbGib,
+        }
+    } catch (error) {
+        const errorMsg = `${lc} ${extractErrorMsg(error)}`;
+        console.error(errorMsg);
+        throw new Error(errorMsg);
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+/**
+ * API function info for the getContextInfo command.
+ */
+export const getContextInfoFunctionInfo: APIFunctionInfo<typeof getContextInfoViaCmd> = {
+    nameOrId: 'getContextInfo',
+    fnViaCmd: getContextInfoViaCmd,
+    functionImpl: getContextInfoImpl,
+    cmd: 'agent',
+    cmdModifiers: ['getContextInfo'],
+    schema: {
+        name: 'getContextInfo',
+        description: `Gets context info *about your current context ibgib in which you are conversing*. For example, agent's must always "be" in a single location ibgib which is their current primary context. When this ibgib's timeline changes (when a mut8/rel8 happens on it and a new ibgib frame is registered with the metaspace and published via the metaspace's pubsub mechanism), then the agent will be made aware of the new children ibgibs added to that timeline. The context address will probably be the TJP address as this defines the timeline's starting point and is used to refer to the entire timeline. Note that the context will always be in the agent's super space.\nNOTE: This function DOES NOT get any and all context info, e.g., it does not get the website's current css colors. It is specifically to get info regarding YOUR CURRENT default context ibgib info.\n\n${EXAMPLES}`,
+        parameters: {
+            type: 'object',
+            properties: {
+                ...COMMAND_BASE_SCHEMA_PROPERTIES,
+                agentId: GEMINI_SCHEMA_AGENT_ID,
+                agentType: GEMINI_SCHEMA_AGENT_TYPE,
+            },
+            required: ['agentId', 'agentType'],
+        },
+    },
+};

package/src/api/commands/chat/hello-world.mts

@@ -0,0 +1,183 @@
+import { extractErrorMsg, pretty } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+
+import { GLOBAL_LOG_A_LOT } from "../../../constants.mjs";
+import { APIFunctionInfo } from "../../api-types.mjs";
+import { COMMAND_BASE_SCHEMA_PROPERTIES } from "../command-constants.mjs";
+import { getCommandService } from "../command-service-v1.mjs";
+import { CommandDataBase } from "../command-types.mjs";
+import { FUNCTION_CALL_EXAMPLES_HEADER } from "../../api-constants.mjs";
+import { AGENT_NAME_REGEXP, GEMINI_SCHEMA_AGENTS_SELF_IDENTIFIED_NAME } from "../../../witness/agent/agent-constants.mjs";
+import { getAgentsSvc } from "../../../witness/agent/agents-service-v1.mjs";
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+// #region constants
+
+/**
+ * camelCased name of the command itself.
+ */
+const FUNCTION_NAME = 'helloWorld';
+
+/**
+ * chat category here as this is a chat-related command.
+ */
+const CMD_CATEGORY = 'agent';
+/**
+ * helloWorld here is the specific command modifier which narrows down to a command
+ * instance, similar to a fully curried function.
+ */
+const CMD_MODIFIERS: string[] = [FUNCTION_NAME];
+
+// #endregion constants
+
+// #region constants
+const EXAMPLE_INPUT_HELLOWORLD: Partial<HelloWorldOpts> = {
+    agentsSelfIdentifiedName: 'Coolguy',
+    agentId: 'someidprobablylookslikeahash',
+    agentType: 'sometypehere',
+    notesToSelf: 'Example of a helloWorld function call. DO NOT USE THESE AS YOUR ACTUAL NAME/ID/TYPE! THIS IS ONLY AN EXAMPLE TO SHOW THE SHAPE OF THE FUNCTION CALL!!',
+    repromptWithResult: false,
+};
+
+const EXAMPLES = [
+    // `\`\`\`typescript\n${FUNCTION_CALL_EXAMPLES_HEADER}\n${pretty(EXAMPLE_INPUT_HELLOWORLD)}\n\`\`\``,
+    FUNCTION_CALL_EXAMPLES_HEADER,
+    pretty(EXAMPLE_INPUT_HELLOWORLD),
+].join('\n');
+// #endregion constants
+const FUNCTION_DESCRIPTION = [
+    `Introductory function that does a couple things. First, it just makes sure that the basic function calling plumbing is working with the agent. Next, it also confirms the agent is aware of his/her/its id and type. Also, it empowers the agent to choose his/her/its own name with which to interact with user(s) and other agent(s) (only one user implemented atow 04/2025).NOTE: This does not say anything to the user proper. You have to call tellUser (or some other function in the future possibly) to converse with the user. This function only does init.`,
+    EXAMPLES,
+].join('\n');
+
+
+const GEMINI_SCHEMA_AGENT_ID = {
+    type: 'string',
+    description: 'unique identifier for the agent. Should be provided to the agent in system instructions upon creation.',
+};
+
+const GEMINI_SCHEMA_AGENT_TYPE = {
+    type: 'string',
+    description: 'type of the agent that governs basic responsibilities. Should be provided to the agent in system instructions upon creation.',
+};
+
+/**
+ * @interface HelloWorldOpts - Options for the helloWorld command.
+ * @extends CommandDataBase
+ */
+export interface HelloWorldOpts extends CommandDataBase<typeof CMD_CATEGORY, typeof CMD_MODIFIERS> {
+    /**
+     * @property agentsSelfIdentifiedName - the name which the agent chooses to
+     * use to represent him/her/itself.
+     */
+    agentsSelfIdentifiedName: string;
+    /**
+     * @property agentId - the agent's unique identifier.
+     */
+    agentId: string;
+    /**
+     * @property agentType - type of the agent that corresponds to the basic
+     * responsibilities of the agent
+     */
+    agentType: string;
+}
+
+/**
+ * @interface HelloWorldCommandData - Command data for the helloWorld command.
+ * @extends CommandDataBase
+ */
+export interface HelloWorldCommandData extends CommandDataBase<typeof CMD_CATEGORY, typeof CMD_MODIFIERS> {
+    /**
+     * @see {@link HelloWorldOpts.agentsSelfIdentifiedName}
+     */
+    agentsSelfIdentifiedName: string;
+    /**
+     * @see {@link HelloWorldOpts.agentId}
+     */
+    agentId: string;
+    /**
+     * @see {@link HelloWorldOpts.agentType}
+     */
+    agentType: string;
+}
+
+/**
+ * Wrapper function to enqueue the helloWorld command.
+ * @param {HelloWorldOpts} opts - Options for telling the user something.
+ * @returns {Promise<void>} A promise that resolves when the command is enqueued.
+ */
+function helloWorldViaCmd(opts: HelloWorldOpts): Promise<void | { errorMsg: string }> {
+    const commandService = getCommandService();
+    const command: HelloWorldCommandData = {
+        ...opts,
+        cmd: CMD_CATEGORY,
+        cmdModifiers: CMD_MODIFIERS,
+        // agentsSelfIdentifiedName: opts.agentsSelfIdentifiedName,
+        // agentId: opts.agentId,
+        // agentType: opts.agentType,
+        // repromptWithResult: opts?.repromptWithResult,
+        // notesToSelf: opts?.notesToSelf,
+    };
+    return new Promise<void>((resolve, reject) => {
+        commandService.enqueueCommand({ command, resolve, reject });
+    });
+}
+
+/**
+ * Implementation function for the helloWorld command (atow, does nothing other than resolve).
+ * @param {HelloWorldOpts} opts - Options for telling the user something.
+ * @returns {Promise<void>} A promise that resolves when the command is executed (immediately).
+ */
+async function helloWorldImpl(opts: HelloWorldOpts): Promise<void | { errorMsg: string }> {
+    const lc = `[${helloWorldImpl.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: genuuid)`); }
+
+        const { agentId, agentType, agentsSelfIdentifiedName } = opts;
+
+        // In the actual implementation, this function might trigger some UI update
+        // or logging, but for now, it's just a placeholder.
+        // debugger; // walk through hello-world command
+
+        // should get the agent
+        const agentsSvc = getAgentsSvc();
+        const agent = await agentsSvc.getAgentById({ agentId, agentType });
+        if (!agent) { throw new Error(`agent not found for opts: ${pretty(opts)} (E: b0da990f27c85c29e5bf148299507225)`); }
+
+        // this does the name validation, throws if invalid
+        await agent.updateName({ name: agentsSelfIdentifiedName });
+        // debugger; // does this get hit?
+    } catch (error) {
+        debugger; // error in helloworld
+        const errorMsg = `${lc} ${extractErrorMsg(error)}`;
+        console.error(errorMsg);
+        return { errorMsg };
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+/**
+ * API function info for the helloWorld command.
+ */
+export const helloWorldFunctionInfo: APIFunctionInfo<typeof helloWorldViaCmd> = {
+    nameOrId: FUNCTION_NAME,
+    fnViaCmd: helloWorldViaCmd,
+    functionImpl: helloWorldImpl,
+    cmd: CMD_CATEGORY,
+    cmdModifiers: CMD_MODIFIERS,
+    schema: {
+        name: FUNCTION_NAME,
+        description: FUNCTION_DESCRIPTION,
+        parameters: {
+            type: 'object',
+            properties: {
+                ...COMMAND_BASE_SCHEMA_PROPERTIES,
+                agentsSelfIdentifiedName: GEMINI_SCHEMA_AGENTS_SELF_IDENTIFIED_NAME,
+                agentId: GEMINI_SCHEMA_AGENT_ID,
+                agentType: GEMINI_SCHEMA_AGENT_TYPE,
+            },
+            required: ['agentsSelfIdentifiedName', 'agentId', 'agentType'],
+        },
+    },
+};

package/src/api/commands/chat/tell-user.mts

@@ -0,0 +1,241 @@
+import { extractErrorMsg, pretty } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+import { IbGib_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
+import { validateIbGibAddr } from "@ibgib/ts-gib/dist/V1/validate-helper.mjs";
+import { getIbAndGib, } from "@ibgib/ts-gib/dist/helper.mjs";
+import { IbGibAddr, } from "@ibgib/ts-gib/dist/types.mjs";
+import { isPrimitive } from "@ibgib/ts-gib/dist/V1/transforms/transform-helper.mjs";
+import { appendToTimeline } from "@ibgib/core-gib/dist/timeline/timeline-api.mjs";
+import { createCommentIbGib } from "@ibgib/core-gib/dist/common/comment/comment-helper.mjs";
+
+import { GLOBAL_LOG_A_LOT } from "../../../constants.mjs";
+import { APIFunctionInfo } from "../../api-types.mjs";
+import { COMMAND_BASE_SCHEMA_PROPERTIES } from "../command-constants.mjs";
+import { getCommandService } from "../command-service-v1.mjs";
+import { CommandDataBase } from "../command-types.mjs";
+import { FUNCTION_CALL_EXAMPLES_HEADER } from "../../api-constants.mjs";
+import { getGlobalMetaspace_waitIfNeeded } from "../../../helpers.web.mjs";
+import {
+    getAddlMetadataTextForAgentText,
+} from "../../../witness/agent/agent-one-file.mjs";
+import { GEMINI_SCHEMA_AGENTS_SELF_IDENTIFIED_NAME, TextSource } from "../../../witness/agent/agent-constants.mjs";
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+// #region constants
+const FUNCTION_NAME = 'tellUser';
+
+/**
+ * chat category here as this is a chat-related command.
+ */
+const CMD_CATEGORY = 'agent';
+/**
+ * helloWorld here is the specific command modifier which narrows down to a command
+ * instance, similar to a fully curried function.
+ */
+const CMD_MODIFIERS: string[] = [FUNCTION_NAME];
+const EXAMPLE_INPUT_TELLUSER: Partial<TellUserOpts> = {
+    text: 'Hello user, this is an example of how I can tell you something!',
+    agentName: 'Zarquon',
+    notesToSelf: 'Example of a tellUser function call. Note repromptWithResult is false b/c it is ignored with tellUser cmd.',
+    repromptWithResult: false,
+};
+
+const EXAMPLES = [
+    // `\`\`\`typescript\n${FUNCTION_CALL_EXAMPLES_HEADER}\n${pretty(EXAMPLE_INPUT_TELLUSER)}\n\`\`\``,
+    FUNCTION_CALL_EXAMPLES_HEADER,
+    pretty(EXAMPLE_INPUT_TELLUSER),
+].join('\n');
+const FUNCTION_DESCRIPTION = `Use this to talk with the user. DON'T just add text on the canvas! Use this function as it adds a comment to the chat log which the user can see.\n\n${EXAMPLES}`;
+// #endregion constants
+
+
+/**
+ * @interface TellUserOpts - Options for the tellUser command.
+ * @extends CommandDataBase
+ */
+export interface TellUserOpts extends CommandDataBase<typeof CMD_CATEGORY, typeof CMD_MODIFIERS> {
+    /**
+     * @property text - The text to tell the user.
+     */
+    text: string;
+
+    /**
+     * agent's id doing the telling
+     */
+    agentId: string;
+
+    /**
+     * address to the context in which the agent is communicating to a user.
+     */
+    contextIbGibAddr: IbGibAddr;
+
+    /**
+     * @property agentName - the name which the model chooses to
+     * use to represent him/her/itself.
+     */
+    agentName: string;
+}
+
+/**
+ * @interface TellUserCommandData - Command data for the tellUser command.
+ * @extends CommandDataBase
+ */
+export interface TellUserCommandData extends CommandDataBase<typeof CMD_CATEGORY, typeof CMD_MODIFIERS> {
+    /**
+     * @property text - The text to tell the user.
+     */
+    text: string;
+}
+
+/**
+ * Wrapper function to enqueue the tellUser command.
+ * @param {TellUserOpts} opts - Options for telling the user something.
+ * @returns {Promise<void>} A promise that resolves when the command is enqueued.
+ */
+function tellUserViaCmd(opts: TellUserOpts): Promise<void> {
+    const lc = `[${tellUserViaCmd.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 39ce6d58e154b8463170463f20d44925)`); }
+        if (logalot) { console.log(`${lc} tellUserViaCmd raw incoming opts: ${pretty(opts)} (I: 2ff6e7fc49b12e335affa1cb3af11125)`); }
+
+        const commandService = getCommandService();
+        const command: TellUserCommandData = {
+            ...opts,
+            cmd: 'agent',
+            cmdModifiers: ['tellUser'],
+            repromptWithResult: false, // override for tellUser
+            // text: opts.text,
+            // repromptWithResult: opts?.repromptWithResult,
+            // notesToSelf: opts?.notesToSelf,
+        };
+        if (logalot) { console.log(`${lc} tellUserViaCmd command: ${pretty(command)} (I: d7c86c41cf2578e1ccdd30f4dbc62625)`); }
+        return new Promise<void>((resolve, reject) => {
+            commandService.enqueueCommand({ command, resolve, reject });
+        });
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+/**
+ * Implementation function for the tellUser command.
+ *
+ * ## notes on context
+ *
+ * LLMs are designed to say/do something upon being prompted. In code, however,
+ * it is beneficial to sometimes just give information and let the agent decide
+ * whether or not to act upon it. Right now I have this doubling as an "ack"
+ * command that acts like a blackhole for when the agent decides no action is
+ * required. So if the context is a primitive, then this will "fail" silently.
+ *
+ *
+ * @param {TellUserOpts} opts - Options for telling the user something.
+ * @returns {Promise<void>} A promise that resolves when the command is executed (immediately).
+ */
+async function tellUserImpl(opts: TellUserOpts): Promise<void> {
+    const lc = `[${tellUserImpl.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: badce195ed1817dd686c7098511e1f25)`); }
+
+        console.log(`${lc} agent tell user opts: ${pretty(opts)}`);
+
+        const metaspace = await getGlobalMetaspace_waitIfNeeded();
+        const contextAddr = opts.contextIbGibAddr;
+        if (!contextAddr) { throw new Error(`contextIbGibAddr is falsy (was not provided by model if this was a function call request). This should be required in the gemini schema. (E: 2585778dc7f6fc74322f40745d7f4d25)`); }
+
+        const addrErrors = validateIbGibAddr({ addr: contextAddr }) ?? [];
+        if (addrErrors.length > 0) {
+            console.log(`${lc} returning early because agent has provided a non-ibgib addr for contextAddr: ${contextAddr}. addrErrors: ${addrErrors}. opts: ${pretty(opts)} (I: 66c39c5031723254de46c254b096dc25)`)
+            return; /* <<<< returns early */
+        }
+        if (isPrimitive({ gib: getIbAndGib({ ibGibAddr: contextAddr }).gib })) {
+            console.log(`${lc} agent has acked by calling this with a primitive context address. This will not propagate to the user's current context. opts: ${pretty(opts)} (I: a0687328201af74ed9d9e24ad4a5b825)`);
+            return; /* <<<< returns early */
+        }
+        const space = await metaspace.getLocalUserSpace({ lock: false });
+        if (!space) { throw new Error(`(UNEXPECTED) couldn't get default local user space? (E: 2fdac9f814d620ce6341cfc10942f525)`); }
+
+        // adding agent name elsewhere
+        // const agentNamePlusText = `${opts.agentName}: ${opts.text}`;
+
+        // create the comment
+        const { newIbGib: commentIbGib } = await createCommentIbGib({
+            text: opts.text,
+            addlMetadataText: getAddlMetadataTextForAgentText({
+                textSrc: TextSource.AI,
+                other: `${opts.agentName}_${opts.agentId}`,
+            }),
+            saveInSpace: true,
+            space,
+        });
+
+        // get the latest context ibgib
+        let latestContextIbGib: IbGib_V1 | undefined = undefined;
+        const latestContextAddr = await metaspace.getLatestAddr({
+            addr: contextAddr,
+            space,
+        });
+        if (latestContextAddr) {
+            const resGetLatest = await metaspace.get({
+                addrs: [latestContextAddr],
+                space,
+            });
+            if (resGetLatest.errorMsg || (resGetLatest.ibGibs ?? []).length !== 1) {
+                throw new Error(`couldn't get latest context ibgib (${latestContextAddr}) from super space (${space.ib}). errorMsg: ${resGetLatest.errorMsg ?? '[unknown error]'} (E: 450727cc12e226f8b741dd7b0efbfe25)`);
+            }
+            latestContextIbGib = resGetLatest.ibGibs!.at(0)!;
+        }
+        if (!latestContextIbGib) { throw new Error(`(UNEXPECTED) couldn't get latest context ibgib? (${latestContextAddr}) (E: cb50a6cb984a60c139a4f16a26290d25)`); }
+
+        await appendToTimeline({
+            timeline: latestContextIbGib,
+            metaspace,
+            rel8nInfos: [{ rel8nName: 'comment', ibGibs: [commentIbGib], }],
+            space,
+        });
+
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+const GEMINI_SCHEMA_TELL_USER_TEXT = {
+    type: 'string',
+    description: 'The text content to display to the user in the chat log. This is how you, as the agent, communicate with the user.',
+};
+
+const GEMINI_SCHEMA_TELL_USER_CONTEXT_ADDR = {
+    type: 'string',
+    description: `This is the address of the ibgib in which you wish to communicate with the user (and/or other agents when implemented). If you don't know this, you should call the getContextInfo function (the actual name may vary slightly as we are in active development right now, but this should be included in your available functions).`,
+};
+
+/**
+ * API function info for the tellUser command.
+ */
+export const tellUserFunctionInfo: APIFunctionInfo<typeof tellUserViaCmd> = {
+    nameOrId: FUNCTION_NAME,
+    fnViaCmd: tellUserViaCmd,
+    functionImpl: tellUserImpl,
+    cmd: CMD_CATEGORY,
+    cmdModifiers: CMD_MODIFIERS,
+    schema: {
+        name: FUNCTION_NAME,
+        description: FUNCTION_DESCRIPTION,
+        parameters: {
+            type: 'object',
+            properties: {
+                ...COMMAND_BASE_SCHEMA_PROPERTIES,
+                text: GEMINI_SCHEMA_TELL_USER_TEXT,
+                contextIbGibAddr: GEMINI_SCHEMA_TELL_USER_CONTEXT_ADDR,
+                agentName: GEMINI_SCHEMA_AGENTS_SELF_IDENTIFIED_NAME,
+            },
+            required: ['text', 'contextIbGibAddr', 'agentName'],
+        },
+    },
+};

package/src/api/commands/command-constants.mts

@@ -0,0 +1,17 @@
+import { GEMINI_SCHEMA_AGENT_ID, GEMINI_SCHEMA_AGENTS_SELF_IDENTIFIED_NAME } from "../../witness/agent/agent-constants.mjs";
+
+/**
+ * common properties for available functions passed to models.
+ */
+export const COMMAND_BASE_SCHEMA_PROPERTIES = {
+    agentId: GEMINI_SCHEMA_AGENT_ID,
+    agentName: GEMINI_SCHEMA_AGENTS_SELF_IDENTIFIED_NAME,
+    repromptWithResult: {
+        type: 'boolean',
+        description: `Set this to true if you want to be reprompted with the function's result. Unless you really want a fire-and-forget style of function call, set this to true. NOTE: This is ignored with tellUser command, so you can't call tellUser and then repromptWithResult of true and then tellUser again.`,
+    },
+    notesToSelf: {
+        type: 'string',
+        description: 'Quick note scratchpad related to a requested function. For example, you could write your intent here.',
+    },
+} as const;