@opengeni/runtime 4.3.0 → 4.4.0-canary.36919050519001

package/dist/agent-instructions/base-behavior.d.ts

@@ -0,0 +1,8 @@
+import { type AgentPromptContext } from "./types.js";
+/**
+ * The one rule the legacy contract lacked: embedder text wins over OpenGeni's
+ * behavior defaults, never over the runtime or safety rules.
+ */
+export declare const INSTRUCTION_PRECEDENCE = "Product, workspace, and session instructions take precedence over the default behavior described here, such as tone, length, and format. They never override the runtime mechanics or the rules on authorization and destructive actions.";
+/** Always on: how to communicate, how much to do, when to ask, truthfulness, and safety. */
+export declare function renderBaseBehavior(context: AgentPromptContext): string;

package/dist/agent-instructions/compose.d.ts

@@ -0,0 +1,59 @@
+import type { ModelContextInstructionLayerId, ModelContextInstructionModule, ResolvedAgentCapabilities, AgentRenderer } from "@opengeni/contracts";
+import type { AgentPromptContext, AgentPromptModule, AgentPromptResources } from "./types.js";
+/**
+ * Conditional modules in composition order. Session-stable modules first;
+ * `attachments` (per turn) last so a file attachment changes as little of the
+ * cached prefix as possible.
+ */
+export declare const AGENT_PROMPT_MODULES: readonly AgentPromptModule[];
+export type ModularInstructionLayer = {
+    id: ModelContextInstructionLayerId;
+    title: string;
+    content: string;
+    modules?: readonly ModelContextInstructionModule[];
+    /** Separator placed before this layer when layers are joined. */
+    joinBefore: string;
+};
+export type ComposeModularAgentInstructionsInput = {
+    capabilities: ResolvedAgentCapabilities;
+    renderer: AgentRenderer;
+    /** The resolved identity (see `resolveAgentIdentity`). */
+    identity: string;
+    resources: AgentPromptResources;
+    /** Per-attempt runtime directives, each already gated by its caller. */
+    codemode?: string | undefined;
+    codeSearch?: string | undefined;
+    gitBindings?: string | undefined;
+    /** Rendered Skill index, only when it is not delivered in conversation history. */
+    skillCatalog?: string | undefined;
+    workspaceGovernance?: string | undefined;
+    workspaceMemory?: string | undefined;
+    sessionInstructions?: string | undefined;
+};
+export declare const MODULAR_LAYER_SEPARATOR = "\n\n";
+/**
+ * Heads the session instructions so the precedence rule has a concrete target
+ * right where the instructions are, at the end of the prompt.
+ */
+export declare const SESSION_INSTRUCTIONS_PREAMBLE = "# Session instructions\n\nThese instructions were set for this session. Follow them over the default behavior above, such as tone, length, and format.\n\n";
+/**
+ * The operational contract for a session with an agent configuration: base
+ * behavior and runtime mechanics (always), then every module whose capability
+ * or resource is present. Pure and deterministic: the same configuration and
+ * resources always produce the same bytes.
+ */
+export declare function composeOperationalContract(context: AgentPromptContext): {
+    content: string;
+    modules: ModelContextInstructionModule[];
+};
+/**
+ * Layer order: identity → operational contract (base, mechanics, modules) →
+ * attempt directives → Skill index → workspace governance → historical memory →
+ * session instructions. Everything up to the directives is the stable,
+ * cache-friendly prefix; governance and session text follow it, and session
+ * instructions come last so they refine everything above.
+ */
+export declare function composeModularAgentInstructions(input: ComposeModularAgentInstructionsInput): {
+    layers: ModularInstructionLayer[];
+    composed: string;
+};

package/dist/agent-instructions/identity.d.ts

@@ -0,0 +1,21 @@
+/**
+ * OpenGeni's default identity: who the agent is and its voice. It is the only
+ * part of the system text an embedder replaces (`agent.identity`, the
+ * workspace default identity, or a legacy white-label persona). Behavior lives
+ * in base behavior so a replaced identity keeps it.
+ */
+export declare const DEFAULT_AGENT_IDENTITY: string;
+/** A legacy persona template read as identity: the CORE marker is ignored. */
+export declare function identityFromLegacyTemplate(template: string | null | undefined): string | null;
+/**
+ * Identity tiers, each replacing the next: session identity (frozen in the
+ * agent configuration) → workspace identity (explicit default, else the legacy
+ * `agentInstructions` persona) → a deployment persona template that differs
+ * from OpenGeni's default → OpenGeni's default identity. Workspace governance
+ * never drops a tier.
+ */
+export declare function resolveAgentIdentity(input: {
+    sessionIdentity?: string | null | undefined;
+    workspaceIdentity?: string | null | undefined;
+    deploymentTemplate?: string | null | undefined;
+}): string;

package/dist/agent-instructions/index.d.ts

@@ -0,0 +1,6 @@
+export { AGENT_PROMPT_MODULES, MODULAR_LAYER_SEPARATOR, SESSION_INSTRUCTIONS_PREAMBLE, composeModularAgentInstructions, composeOperationalContract, type ComposeModularAgentInstructionsInput, type ModularInstructionLayer, } from "./compose.js";
+export { INSTRUCTION_PRECEDENCE, renderBaseBehavior } from "./base-behavior.js";
+export { renderRuntimeMechanics } from "./runtime-mechanics.js";
+export { DEFAULT_AGENT_IDENTITY, identityFromLegacyTemplate, resolveAgentIdentity, } from "./identity.js";
+export { rigInstructions, workspaceEnvironmentInstructions } from "./modules/environment.js";
+export type { AgentPromptContext, AgentPromptModule, AgentPromptResources, RigInstructionsContext, WorkspaceEnvironmentContext, } from "./types.js";

package/dist/agent-instructions/modules/admin.d.ts

@@ -0,0 +1,3 @@
+import { type AgentPromptModule } from "../types.js";
+/** Integration setup and Variable Set discovery (workspace admin tools). */
+export declare const adminModule: AgentPromptModule;

package/dist/agent-instructions/modules/artifacts.d.ts

@@ -0,0 +1,7 @@
+import { type AgentPromptModule } from "../types.js";
+/**
+ * Documents, published files, Sites, and inline visuals. With the markdown
+ * renderer only the delivery rules remain: `artifact:` links, inline HTML, and
+ * image embedding need OpenGeni's timeline.
+ */
+export declare const artifactsModule: AgentPromptModule;

package/dist/agent-instructions/modules/attachments.d.ts

@@ -0,0 +1,3 @@
+import { type AgentPromptModule } from "../types.js";
+/** Files mounted for this turn. Placed last among modules: it varies per turn. */
+export declare const attachmentsModule: AgentPromptModule;

package/dist/agent-instructions/modules/environment.d.ts

@@ -0,0 +1,11 @@
+import type { RigInstructionsContext, WorkspaceEnvironmentContext } from "../types.js";
+import { type AgentPromptModule } from "../types.js";
+/**
+ * Rig doctrine lines. Shared with the legacy CORE, whose bytes they keep.
+ */
+export declare function rigInstructions(rig: RigInstructionsContext): string[];
+/** Workspace environment lines (metadata only). Shared with the legacy CORE. */
+export declare function workspaceEnvironmentInstructions(environment: WorkspaceEnvironmentContext): string[];
+export declare const workspaceEnvironmentModule: AgentPromptModule;
+/** The rig lines naming rig tools appear only when workspace admin tools are available. */
+export declare const rigModule: AgentPromptModule;

package/dist/agent-instructions/modules/goals.d.ts

@@ -0,0 +1,3 @@
+import { type AgentPromptModule } from "../types.js";
+/** The goal loop: owning, completing, pausing, and resuming a session goal. */
+export declare const goalsModule: AgentPromptModule;

package/dist/agent-instructions/modules/knowledge.d.ts

@@ -0,0 +1,6 @@
+import { type AgentPromptModule } from "../types.js";
+/**
+ * Durable storage choice, workspace-instruction editing, and Knowledge
+ * retrieval/retention doctrine (the legacy CORE text, split into paragraphs).
+ */
+export declare const knowledgeModule: AgentPromptModule;

package/dist/agent-instructions/modules/machines.d.ts

@@ -0,0 +1,3 @@
+import { type AgentPromptModule } from "../types.js";
+/** The active compute is a Connected Machine: the owner's real filesystem and host-native paths. */
+export declare const connectedMachineModule: AgentPromptModule;

package/dist/agent-instructions/modules/renderer-markdown.d.ts

@@ -0,0 +1,6 @@
+import { type AgentPromptModule } from "../types.js";
+/**
+ * The client renders plain Markdown (Slack, the chat facade, a product's own
+ * UI). Replaces the `sandbox:`/`artifact:` link and inline-visual rules.
+ */
+export declare const rendererMarkdownModule: AgentPromptModule;

package/dist/agent-instructions/modules/repositories.d.ts

@@ -0,0 +1,7 @@
+import { type AgentPromptModule } from "../types.js";
+/**
+ * Repository resources, Git provider credentials, or a Connected Machine (which
+ * owns its own checkouts): mount paths, provider CLIs, branch/pull-request
+ * policy, and Git safety.
+ */
+export declare const repositoriesModule: AgentPromptModule;

package/dist/agent-instructions/modules/sandbox.d.ts

@@ -0,0 +1,3 @@
+import { type AgentPromptModule } from "../types.js";
+/** Any attached compute (managed sandbox or Connected Machine): shell, files, and file links. */
+export declare const sandboxModule: AgentPromptModule;

package/dist/agent-instructions/modules/skills.d.ts

@@ -0,0 +1,3 @@
+import { type AgentPromptModule } from "../types.js";
+/** Reading and following Skills. Present whenever Skills are readable. */
+export declare const skillsModule: AgentPromptModule;

package/dist/agent-instructions/modules/subagents.d.ts

@@ -0,0 +1,3 @@
+import { type AgentPromptModule } from "../types.js";
+/** Session tools: reading history, managing sessions, delegating to children, and joining them. */
+export declare const subagentsModule: AgentPromptModule;

package/dist/agent-instructions/runtime-mechanics.d.ts

@@ -0,0 +1,7 @@
+import { type AgentPromptContext } from "./types.js";
+/**
+ * Always on: how the durable runtime behaves for every agent — messages that
+ * arrive mid-turn, `wait_for_input`, compaction, and background commands.
+ * Embedder instructions do not override these.
+ */
+export declare function renderRuntimeMechanics(context: AgentPromptContext): string;

package/dist/agent-instructions/types.d.ts

@@ -0,0 +1,55 @@
+import type { AgentPromptModuleId, AgentRenderer, ResolvedAgentCapabilities } from "@opengeni/contracts";
+/**
+ * Metadata about the workspace environment attached to a run. Surfaced
+ * verbatim in the agent instructions: the description is where operators
+ * document how the exported credentials are meant to be used. Only metadata
+ * belongs here — never variable values.
+ */
+export type WorkspaceEnvironmentContext = {
+    name: string;
+    description?: string | null;
+    variableNames?: string[];
+};
+/** The rig (versioned sandbox environment) a session rides. */
+export type RigInstructionsContext = {
+    name: string;
+    version: number;
+};
+/**
+ * What the session is attached to, as far as its instructions care. Every flag
+ * must be derived from session-level facts (or the exact turn's resources for
+ * attachments) so the composed prefix only changes when they change.
+ */
+export type AgentPromptResources = {
+    /** A managed (provisioned) sandbox is the active compute. */
+    managedSandbox: boolean;
+    /** A Connected Machine is the active compute. */
+    connectedMachine: boolean;
+    /** Repository resources are mounted in the workspace. */
+    repositories: boolean;
+    /** Git provider credentials were delivered to the sandbox. */
+    gitCredentials: boolean;
+    /** Files are attached (mounted) for this turn. */
+    attachments: boolean;
+    workspaceEnvironment?: WorkspaceEnvironmentContext | undefined;
+    rig?: RigInstructionsContext | undefined;
+};
+/** Everything a prompt module may read. Pure data; no settings, no clock. */
+export type AgentPromptContext = {
+    capabilities: ResolvedAgentCapabilities;
+    renderer: AgentRenderer;
+    resources: AgentPromptResources;
+};
+/** One conditional section of the operational contract. */
+export type AgentPromptModule = {
+    id: AgentPromptModuleId;
+    applies: (context: AgentPromptContext) => boolean;
+    render: (context: AgentPromptContext) => string;
+};
+export declare function hasSandbox(context: AgentPromptContext): boolean;
+/** Joins non-empty blocks with blank lines. */
+export declare function blocks(...parts: ReadonlyArray<string | false | null | undefined>): string;
+/** Joins non-empty sentences with single spaces. */
+export declare function sentences(...parts: ReadonlyArray<string | false | null | undefined>): string;
+/** Renders a Markdown bullet list from non-empty items. */
+export declare function bullets(...items: ReadonlyArray<string | false | null | undefined>): string;