@datalayer/agent-runtimes 1.5.36 → 1.5.37

package/lib/apps/apps/sessionRules.d.ts

@@ -0,0 +1,81 @@
+/**
+ * A rule a person adds to a running session (SHIELD.md §6.3, SH-54): the
+ * session API's `/apps/sessions/{uid}/rules`, read and written from the
+ * Rules card beside the page, and the words it says.
+ *
+ * The rule is the Shield's own shape (`@datalayer/agent-shield`'s `Rule`): a
+ * name, a decision — `allow`, `ask`, `deny` — and what it names: classes
+ * (read, write, send, buy, delete, execute), a harness's kinds, where, paths,
+ * commands. It may only tighten: one that would permit more than the
+ * organization's rules is refused by the runtime in a sentence, shown as is.
+ * The phone's panel speaks to the same three routes with the same shapes.
+ *
+ * @module apps/apps/sessionRules
+ */
+export declare const SESSION_RULE_DECISIONS: readonly ["allow", "ask", "deny"];
+export type SessionRuleDecision = (typeof SESSION_RULE_DECISIONS)[number];
+export declare const SESSION_RULE_CLASSES: readonly ["read", "write", "send", "buy", "delete", "execute"];
+export type SessionRuleClass = (typeof SESSION_RULE_CLASSES)[number];
+/** One rule of a session, as the runtime keeps it. */
+export interface SessionRule {
+    name: string;
+    decision: SessionRuleDecision;
+    classes?: string[];
+    kinds?: string[];
+    where?: 'inside' | 'outside' | 'any';
+    paths?: string[];
+    commands?: string[];
+    reason?: string | null;
+}
+/** One policy document in force, as the runtime answers it. */
+export interface PolicyInForce {
+    scope: 'organization' | 'team' | 'session';
+    version?: number;
+    rules?: SessionRule[];
+    limits?: Record<string, {
+        soft: number;
+        hard: number;
+    } | null>;
+}
+/** What decides a session now (`GET /apps/sessions/{uid}/rules`). */
+export interface RulesInForce {
+    uid: string;
+    harness: string | null;
+    managed?: boolean;
+    policies: PolicyInForce[];
+    session_rules: SessionRule[];
+    /** The sentence when nothing can be decided (SHIELD decision 11), else null. */
+    unavailable: string | null;
+}
+/** The words of the card's session section. */
+export declare const SESSION_RULES_WORDS: {
+    readonly title: "This session";
+    readonly none: "No rule of your own on this session yet.";
+    readonly noSession: "Start a conversation to add a rule to its session.";
+    readonly add: "Add";
+    readonly remove: "Remove";
+    readonly namePlaceholder: "A name, quoted in every sentence it decides";
+    readonly decisions: Record<SessionRuleDecision, string>;
+    readonly classes: Record<SessionRuleClass, string>;
+    readonly scopes: Record<PolicyInForce["scope"], string>;
+    readonly goneWithSession: "In force at once, for this session only; gone when it ends.";
+    readonly unavailable: (sentence: string) => string;
+};
+/** A rule in words: *writing, sending: leave it to me*. */
+export declare function sessionRuleInWords(rule: SessionRule): string;
+/** What the person typed, as the rule the runtime takes; a sentence when it cannot be one. */
+export declare function sessionRuleOf(input: {
+    name: string;
+    decision: string;
+    classes: string[];
+}): SessionRule | string;
+/** Where the session API answers from, for one session. */
+export declare const sessionRulesUrl: (agentServerUrl: string, sessionUid: string) => string;
+type Fetch = typeof fetch;
+/** What decides the session now. */
+export declare function readSessionRules(agentServerUrl: string, token: string, sessionUid: string, fetcher?: Fetch): Promise<RulesInForce>;
+/** Add or tighten a rule on the session; the runtime answers what is in force now. */
+export declare function addSessionRule(agentServerUrl: string, token: string, sessionUid: string, rule: SessionRule, fetcher?: Fetch): Promise<RulesInForce>;
+/** Take a session rule back. */
+export declare function removeSessionRule(agentServerUrl: string, token: string, sessionUid: string, name: string, fetcher?: Fetch): Promise<RulesInForce>;
+export {};

package/lib/apps/apps/sessionRules.js

@@ -0,0 +1,122 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * A rule a person adds to a running session (SHIELD.md §6.3, SH-54): the
+ * session API's `/apps/sessions/{uid}/rules`, read and written from the
+ * Rules card beside the page, and the words it says.
+ *
+ * The rule is the Shield's own shape (`@datalayer/agent-shield`'s `Rule`): a
+ * name, a decision — `allow`, `ask`, `deny` — and what it names: classes
+ * (read, write, send, buy, delete, execute), a harness's kinds, where, paths,
+ * commands. It may only tighten: one that would permit more than the
+ * organization's rules is refused by the runtime in a sentence, shown as is.
+ * The phone's panel speaks to the same three routes with the same shapes.
+ *
+ * @module apps/apps/sessionRules
+ */
+export const SESSION_RULE_DECISIONS = ['allow', 'ask', 'deny'];
+export const SESSION_RULE_CLASSES = [
+    'read',
+    'write',
+    'send',
+    'buy',
+    'delete',
+    'execute',
+];
+/** The words of the card's session section. */
+export const SESSION_RULES_WORDS = {
+    title: 'This session',
+    none: 'No rule of your own on this session yet.',
+    noSession: 'Start a conversation to add a rule to its session.',
+    add: 'Add',
+    remove: 'Remove',
+    namePlaceholder: 'A name, quoted in every sentence it decides',
+    decisions: {
+        allow: 'do it',
+        ask: 'ask me first',
+        deny: 'leave it to me',
+    },
+    classes: {
+        read: 'reading',
+        write: 'writing',
+        send: 'sending',
+        buy: 'buying',
+        delete: 'deleting',
+        execute: 'running a command',
+    },
+    scopes: {
+        organization: 'your organization',
+        team: 'this application',
+        session: 'this session',
+    },
+    goneWithSession: 'In force at once, for this session only; gone when it ends.',
+    unavailable: (sentence) => `Nothing is decided right now: ${sentence}`,
+};
+/** A rule in words: *writing, sending: leave it to me*. */
+export function sessionRuleInWords(rule) {
+    const classes = (rule.classes ?? []).map(item => SESSION_RULES_WORDS.classes[item] ?? item);
+    const covers = classes.length > 0 ? classes.join(', ') : 'everything';
+    return `${covers}: ${SESSION_RULES_WORDS.decisions[rule.decision]}`;
+}
+/** What the person typed, as the rule the runtime takes; a sentence when it cannot be one. */
+export function sessionRuleOf(input) {
+    const name = input.name.trim();
+    if (!name) {
+        return 'A rule needs a name: it is quoted in every sentence it decides.';
+    }
+    if (!SESSION_RULE_DECISIONS.includes(input.decision)) {
+        return `A rule says ${SESSION_RULE_DECISIONS.join(', ')}, not “${input.decision}”.`;
+    }
+    const classes = input.classes.filter(item => SESSION_RULE_CLASSES.includes(item));
+    return {
+        name,
+        decision: input.decision,
+        classes,
+    };
+}
+/** Where the session API answers from, for one session. */
+export const sessionRulesUrl = (agentServerUrl, sessionUid) => `${agentServerUrl}/api/v1/apps/sessions/${encodeURIComponent(sessionUid)}/rules`;
+function parsed(text) {
+    try {
+        return text ? JSON.parse(text) : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function answered(response, what) {
+    const body = parsed(await response.text());
+    if (!response.ok) {
+        const detail = body && typeof body === 'object' && 'detail' in body
+            ? String(body.detail)
+            : `${what} (${response.status})`;
+        throw new Error(detail);
+    }
+    return body;
+}
+/** What decides the session now. */
+export async function readSessionRules(agentServerUrl, token, sessionUid, fetcher = fetch) {
+    const response = await fetcher(sessionRulesUrl(agentServerUrl, sessionUid), {
+        headers: { Authorization: `Bearer ${token}` },
+    });
+    return answered(response, 'The rules of the session could not be read');
+}
+/** Add or tighten a rule on the session; the runtime answers what is in force now. */
+export async function addSessionRule(agentServerUrl, token, sessionUid, rule, fetcher = fetch) {
+    const response = await fetcher(sessionRulesUrl(agentServerUrl, sessionUid), {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${token}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(rule),
+    });
+    return answered(response, 'The rule could not be added');
+}
+/** Take a session rule back. */
+export async function removeSessionRule(agentServerUrl, token, sessionUid, name, fetcher = fetch) {
+    const response = await fetcher(`${sessionRulesUrl(agentServerUrl, sessionUid)}/${encodeURIComponent(name)}`, { method: 'DELETE', headers: { Authorization: `Bearer ${token}` } });
+    return answered(response, 'The rule could not be removed');
+}

package/lib/apps/plugins/app-rules/AppRulesCard.d.ts

@@ -12,6 +12,7 @@
  */
 import type { JSX } from 'react';
 import type { AppRuleSpec, AppSpec } from '../../../types/agentspecs';
+import { type LoopWorkspaceContext } from '../../core';
 import { type Draft } from '../../apps/saved';
 import { type ApprovalRecord } from '../../../hooks/useToolApprovals';
 /** What the card says. */
@@ -50,7 +51,19 @@ export declare function approvalsOfApp(approvals: ApprovalRecord[], appId: strin
 export declare function DraftShown({ draft }: {
     draft: Draft;
 }): JSX.Element;
-export declare function AppRulesCard({ app }: {
+/**
+ * The rules of the running session (SHIELD §6.3, SH-54): what decides it now,
+ * the rules the person added, and a rule to add — in force at once, gone with
+ * the session, never below the organization's.
+ */
+export declare function SessionRules({ agentServerUrl, sessionUid, token, }: {
+    agentServerUrl: string;
+    sessionUid: string;
+    token: string;
+}): JSX.Element;
+export declare function AppRulesCard({ app, workspace, }: {
     app: AppSpec;
+    /** The workspace the card sits in, when the slot gives it: names the session running. */
+    workspace?: LoopWorkspaceContext;
 }): JSX.Element;
 export default AppRulesCard;

package/lib/apps/plugins/app-rules/AppRulesCard.js

@@ -1,9 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useMemo } from 'react';
-import { Button, Heading, Label, Text } from '@primer/react';
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { Button, Heading, Label, Select, Text, TextInput } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
 import { useIAMStore } from '@datalayer/core/lib/state/substates/IAMState';
+import { agentServerOf } from '../../core';
 import { BEHAVIOUR_WORDS, coverOf } from '../../apps/rules';
+import { SESSION_RULES_WORDS, SESSION_RULE_CLASSES, SESSION_RULE_DECISIONS, addSessionRule, readSessionRules, removeSessionRule, sessionRuleInWords, sessionRuleOf, } from '../../apps/sessionRules';
 import { SAVE_WORDS, draftOfApproval } from '../../apps/saved';
 import { useApproveToolRequest, useRejectToolRequest, useToolApprovalsQuery, } from '../../../hooks/useToolApprovals';
 /** What the card says. */
@@ -61,8 +63,57 @@ function Approvals({ app }) {
                     return (_jsxs(Box, { as: "li", py: 2, borderTop: "1px solid", borderColor: "border.muted", fontSize: 1, children: [_jsx(Text, { sx: { fontWeight: 'semibold' }, children: approval.tool_name }), ruleOfApproval(approval) ? (_jsx(Text, { as: "p", sx: { m: 0, color: 'fg.muted', fontSize: 0 }, children: ruleOfApproval(approval) })) : null, draft ? _jsx(DraftShown, { draft: draft }) : null, _jsxs(Box, { display: "flex", gap: 2, mt: 1, children: [_jsx(Button, { size: "small", variant: "primary", disabled: approve.isPending, onClick: () => approve.mutate({ id: approval.id }), children: draft ? SAVE_WORDS.approve : APP_RULES_WORDS.approve }), _jsx(Button, { size: "small", disabled: reject.isPending, onClick: () => reject.mutate({ id: approval.id }), children: draft ? SAVE_WORDS.decline : APP_RULES_WORDS.reject })] })] }, approval.id));
                 }) }))] }));
 }
-export function AppRulesCard({ app }) {
-    const signedIn = Boolean(useIAMStore(state => state.token));
-    return (_jsxs(Box, { "data-testid": "app-rules", mb: 4, children: [_jsx(Heading, { as: "h3", sx: { fontSize: 2, mb: 2 }, children: APP_RULES_WORDS.title }), app.rules.length === 0 ? (_jsx(Text, { as: "p", sx: { fontSize: 1, color: 'fg.muted', m: 0 }, children: APP_RULES_WORDS.none })) : (_jsx(Box, { as: "ul", listStyle: "none", p: 0, m: 0, children: app.rules.map(ruleInWords).map((rule, index) => (_jsxs(Box, { as: "li", py: 1, fontSize: 1, children: [_jsx(Text, { children: rule.action }), ' ', _jsx(Label, { title: rule.means, children: rule.says }), _jsx(Text, { as: "p", sx: { m: 0, color: 'fg.muted', fontSize: 0 }, children: rule.covers })] }, index))) })), _jsx(Text, { as: "p", sx: { fontSize: 0, color: 'fg.muted', mt: 1, mb: 0 }, children: APP_RULES_WORDS.byDefault }), signedIn ? (_jsx(Approvals, { app: app })) : (_jsx(Text, { as: "p", sx: { fontSize: 1, color: 'fg.muted', mt: 3, mb: 0 }, children: APP_RULES_WORDS.signedOut }))] }));
+/**
+ * The rules of the running session (SHIELD §6.3, SH-54): what decides it now,
+ * the rules the person added, and a rule to add — in force at once, gone with
+ * the session, never below the organization's.
+ */
+export function SessionRules({ agentServerUrl, sessionUid, token, }) {
+    const [inForce, setInForce] = useState(null);
+    const [problem, setProblem] = useState('');
+    const [name, setName] = useState('');
+    const [decision, setDecision] = useState('ask');
+    const [kind, setKind] = useState('send');
+    const [busy, setBusy] = useState(false);
+    const refresh = useCallback(() => {
+        let cancelled = false;
+        readSessionRules(agentServerUrl, token, sessionUid).then(value => !cancelled && setInForce(value), (error) => !cancelled &&
+            setProblem(error instanceof Error ? error.message : String(error)));
+        return () => {
+            cancelled = true;
+        };
+    }, [agentServerUrl, token, sessionUid]);
+    useEffect(refresh, [refresh]);
+    const act = async (work) => {
+        setBusy(true);
+        setProblem('');
+        try {
+            setInForce(await work());
+        }
+        catch (error) {
+            setProblem(error instanceof Error ? error.message : String(error));
+        }
+        finally {
+            setBusy(false);
+        }
+    };
+    const add = () => {
+        const rule = sessionRuleOf({ name, decision, classes: [kind] });
+        if (typeof rule === 'string') {
+            setProblem(rule);
+            return;
+        }
+        void act(() => addSessionRule(agentServerUrl, token, sessionUid, rule)).then(() => setName(''));
+    };
+    return (_jsxs(Box, { "data-testid": "session-rules", mt: 3, children: [_jsx(Heading, { as: "h4", sx: { fontSize: 1, mb: 1 }, children: SESSION_RULES_WORDS.title }), inForce?.unavailable ? (_jsx(Text, { as: "p", role: "alert", sx: { fontSize: 0, m: 0, mb: 1 }, children: SESSION_RULES_WORDS.unavailable(inForce.unavailable) })) : null, inForce && inForce.session_rules.length === 0 ? (_jsx(Text, { as: "p", sx: { fontSize: 1, color: 'fg.muted', m: 0 }, children: SESSION_RULES_WORDS.none })) : (_jsx(Box, { as: "ul", listStyle: "none", p: 0, m: 0, children: (inForce?.session_rules ?? []).map(rule => (_jsxs(Box, { as: "li", py: 1, fontSize: 1, display: "flex", gap: 2, alignItems: "center", children: [_jsx(Text, { sx: { fontWeight: 'semibold' }, children: rule.name }), _jsx(Text, { sx: { color: 'fg.muted', fontSize: 0 }, children: sessionRuleInWords(rule) }), _jsx(Button, { size: "small", variant: "invisible", disabled: busy, onClick: () => void act(() => removeSessionRule(agentServerUrl, token, sessionUid, rule.name)), children: SESSION_RULES_WORDS.remove })] }, rule.name))) })), _jsxs(Box, { display: "flex", gap: 1, mt: 1, flexWrap: "wrap", alignItems: "center", children: [_jsx(TextInput, { size: "small", value: name, placeholder: SESSION_RULES_WORDS.namePlaceholder, "aria-label": "The rule's name", onChange: event => setName(event.target.value) }), _jsx(Select, { size: "small", value: kind, "aria-label": "What it covers", onChange: event => setKind(event.target.value), children: SESSION_RULE_CLASSES.map(item => (_jsx(Select.Option, { value: item, children: SESSION_RULES_WORDS.classes[item] }, item))) }), _jsx(Select, { size: "small", value: decision, "aria-label": "What it says", onChange: event => setDecision(event.target.value), children: SESSION_RULE_DECISIONS.map(item => (_jsx(Select.Option, { value: item, children: SESSION_RULES_WORDS.decisions[item] }, item))) }), _jsx(Button, { size: "small", disabled: busy, onClick: add, children: SESSION_RULES_WORDS.add })] }), problem ? (_jsx(Text, { as: "p", role: "alert", sx: { fontSize: 0, m: 0, mt: 1 }, children: problem })) : null, _jsx(Text, { as: "p", sx: { fontSize: 0, color: 'fg.muted', mt: 1, mb: 0 }, children: SESSION_RULES_WORDS.goneWithSession })] }));
+}
+export function AppRulesCard({ app, workspace, }) {
+    const token = useIAMStore(state => state.token) ?? '';
+    const signedIn = Boolean(token);
+    const agentServerUrl = workspace
+        ? agentServerOf(workspace.sandbox, workspace.serverUrl)
+        : undefined;
+    const sessionUid = workspace?.conversationId;
+    return (_jsxs(Box, { "data-testid": "app-rules", mb: 4, children: [_jsx(Heading, { as: "h3", sx: { fontSize: 2, mb: 2 }, children: APP_RULES_WORDS.title }), app.rules.length === 0 ? (_jsx(Text, { as: "p", sx: { fontSize: 1, color: 'fg.muted', m: 0 }, children: APP_RULES_WORDS.none })) : (_jsx(Box, { as: "ul", listStyle: "none", p: 0, m: 0, children: app.rules.map(ruleInWords).map((rule, index) => (_jsxs(Box, { as: "li", py: 1, fontSize: 1, children: [_jsx(Text, { children: rule.action }), ' ', _jsx(Label, { title: rule.means, children: rule.says }), _jsx(Text, { as: "p", sx: { m: 0, color: 'fg.muted', fontSize: 0 }, children: rule.covers })] }, index))) })), _jsx(Text, { as: "p", sx: { fontSize: 0, color: 'fg.muted', mt: 1, mb: 0 }, children: APP_RULES_WORDS.byDefault }), signedIn ? (_jsx(Approvals, { app: app })) : (_jsx(Text, { as: "p", sx: { fontSize: 1, color: 'fg.muted', mt: 3, mb: 0 }, children: APP_RULES_WORDS.signedOut })), signedIn && agentServerUrl ? (sessionUid ? (_jsx(SessionRules, { agentServerUrl: agentServerUrl, sessionUid: sessionUid, token: token })) : (_jsx(Text, { as: "p", sx: { fontSize: 0, color: 'fg.muted', mt: 3, mb: 0 }, children: SESSION_RULES_WORDS.noSession }))) : null] }));
 }
 export default AppRulesCard;

package/lib/apps/plugins/app-rules/index.d.ts

@@ -3,5 +3,6 @@ import type { AppSpec } from '../../../types/agentspecs';
 export declare const APP_RULES_PLUGIN_NAME = "@datalayer/loop-plugin-app-rules";
 /** The plugin that lists an application's rules and the approvals waiting for the person. */
 export declare function defineAppRulesPlugin(app: AppSpec): ReactorPlugin<Record<string, never>, unknown, unknown>;
-export { AppRulesCard, APP_RULES_WORDS, ruleInWords, ruleOfApproval, approvalsOfApp, } from './AppRulesCard';
+export { AppRulesCard, SessionRules, APP_RULES_WORDS, ruleInWords, ruleOfApproval, approvalsOfApp, } from './AppRulesCard';
+export { SESSION_RULES_WORDS, sessionRuleInWords, sessionRuleOf, } from '../../apps/sessionRules';
 export default defineAppRulesPlugin;

package/lib/apps/plugins/app-rules/index.js

@@ -7,8 +7,8 @@ export const APP_RULES_PLUGIN_NAME = '@datalayer/loop-plugin-app-rules';
 /** The plugin that lists an application's rules and the approvals waiting for the person. */
 export function defineAppRulesPlugin(app) {
     // One component per plugin: the slot keeps it, and the application with it.
-    function Card() {
-        return _jsx(AppRulesCard, { app: app });
+    function Card(props) {
+        return _jsx(AppRulesCard, { app: app, workspace: props.workspace });
     }
     const plugin = definePlugin({
         name: `${APP_RULES_PLUGIN_NAME}-${app.id}`,
@@ -30,5 +30,6 @@ export function defineAppRulesPlugin(app) {
     });
     return plugin;
 }
-export { AppRulesCard, APP_RULES_WORDS, ruleInWords, ruleOfApproval, approvalsOfApp, } from './AppRulesCard';
+export { AppRulesCard, SessionRules, APP_RULES_WORDS, ruleInWords, ruleOfApproval, approvalsOfApp, } from './AppRulesCard';
+export { SESSION_RULES_WORDS, sessionRuleInWords, sessionRuleOf, } from '../../apps/sessionRules';
 export default defineAppRulesPlugin;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datalayer/agent-runtimes",
-    "version": "1.5.36",
+    "version": "1.5.37",
     "type": "module",
     "workspaces": [
         ".",