@datalayer/agent-runtimes 1.3.106 → 1.3.109

package/lib/specs/apps.js

@@ -558,20 +558,78 @@ export const CUSTOMER_INTERVIEW_APP_0_0_1 = {
         evalset: '',
         cases: [
             {
-                ask: 'The interviewee declines to be recorded.',
-                expect: 'It thanks them, asks nothing more, and saves no insight.',
+                ask: '',
+                turns: [
+                    {
+                        choose: 'No',
+                    },
+                    {
+                        say: 'Ask me why I stopped after the trial.',
+                    },
+                ],
+                expect: 'It thanks them, asks nothing more, even when they write again, and saves no insight.',
             },
             {
-                ask: 'We want to learn why people leave after the trial.',
-                expect: 'It asks open questions about the trial, one at a time, and none that suggests an answer.',
+                ask: '',
+                turns: [
+                    {
+                        choose: 'Yes',
+                    },
+                    {
+                        say: 'We want to learn why people leave after the trial.',
+                    },
+                    {
+                        say: 'I stopped using it when the trial ended.',
+                    },
+                ],
+                expect: 'It asks one open question at a time about the trial, and none that suggests an answer.',
             },
             {
-                ask: 'The interviewee says the price was fine but the setup took a week.',
-                expect: 'It follows up on the setup, and the insight it saves quotes their words about it.',
+                ask: '',
+                turns: [
+                    {
+                        choose: 'Yes',
+                    },
+                    {
+                        say: 'We want to learn why people leave after the trial.',
+                    },
+                    {
+                        say: 'The price was fine, but the setup took a week.',
+                    },
+                    {
+                        press: 'save',
+                        payload: {
+                            insight: 'The setup, not the price, held them back.',
+                            quote: 'The price was fine, but the setup took a week.',
+                        },
+                    },
+                ],
+                expect: 'It follows up on the setup, and the insight saved quotes their words about it.',
             },
             {
-                ask: 'End the interview.',
-                expect: 'It gives the goal, the insights each with its quote, and the questions left open.',
+                ask: '',
+                turns: [
+                    {
+                        choose: 'Yes',
+                    },
+                    {
+                        say: 'We want to learn why people leave after the trial.',
+                    },
+                    {
+                        say: 'The price was fine, but the setup took a week.',
+                    },
+                    {
+                        press: 'save',
+                        payload: {
+                            insight: 'The setup, not the price, held them back.',
+                            quote: 'The price was fine, but the setup took a week.',
+                        },
+                    },
+                    {
+                        press: 'finish',
+                    },
+                ],
+                expect: 'It records the result: the goal, the insight saved with its quote, and the questions the interview left open, which it lists.',
             },
         ],
         verified: {
@@ -2139,7 +2197,7 @@ export const QUOTE_CALCULATOR_APP_0_0_1 = {
     owner: 'Datalayer <info@datalayer.io>',
     agent: 'jupyter-data-analyst:0.0.1',
     team: '',
-    instructions: 'Compute the quote in code from the inputs and the price list. Show each line of the calculation; never estimate a total.',
+    instructions: "Before you write a word, search the price list with search_documents, for every request, even one you refuse. Then compute the quote in code from the inputs and the passages it found. Show each line of the calculation; never estimate a total. A quote needs at least one seat, and at least the plan's minimum_seats of the price list: for fewer, refuse in a sentence that says so, compute nothing, and do not ask what was meant. Call a tool only to read the price list or to compute, never to say or announce something.",
     model: '',
     skills: [],
     backendTools: [],
@@ -2409,7 +2467,7 @@ export const REPORT_FROM_A_FILE_APP_0_0_1 = {
     owner: 'Datalayer <info@datalayer.io>',
     agent: 'jupyter-data-analyst:0.0.1',
     team: '',
-    instructions: 'Analyse the file in code, in the sandbox. Every number in the report is computed from the file; say what you could not read, and never estimate.',
+    instructions: 'You take a CSV file only: asked for a file of another kind (a PDF, a spreadsheet, an image), refuse it in a sentence that says you take a CSV, and ask for nothing. Analyse the file in code, in the sandbox. Every number in the report is computed from the file; say what you could not read, and never estimate.',
     model: '',
     skills: [],
     backendTools: [],
@@ -3233,7 +3291,7 @@ export const SUPPORT_DESK_APP_0_0_1 = {
     owner: 'Datalayer <info@datalayer.io>',
     agent: 'worker-document-qa:0.0.1',
     team: '',
-    instructions: "Answer from the documents you were given only, and cite the passage each answer rests on. When they do not hold the answer, say so and offer to hand the question to a person; never guess. Do nothing on an account: changing, refunding or deleting is a person's.",
+    instructions: "Before you write a word, search the documents you were given, for every message, even a request you decline; answer from them only, and cite the passage each answer rests on. When they do not hold the answer, say so and offer to hand the question to a person, in those words; never guess, and never only tell them to contact someone. Do nothing on an account: changing, refunding or deleting is a person's. Asked to, say a person does it, cite the passage that says so, and offer to hand the request to a person.",
     model: '',
     skills: [],
     backendTools: [],
@@ -4054,20 +4112,74 @@ export const APP_SOURCES = {
         tests: {
             cases: [
                 {
-                    ask: 'The interviewee declines to be recorded.',
-                    expect: 'It thanks them, asks nothing more, and saves no insight.',
+                    turns: [
+                        {
+                            choose: 'No',
+                        },
+                        {
+                            say: 'Ask me why I stopped after the trial.',
+                        },
+                    ],
+                    expect: 'It thanks them, asks nothing more, even when they write again, and saves no insight.',
                 },
                 {
-                    ask: 'We want to learn why people leave after the trial.',
-                    expect: 'It asks open questions about the trial, one at a time, and none that suggests an answer.',
+                    turns: [
+                        {
+                            choose: 'Yes',
+                        },
+                        {
+                            say: 'We want to learn why people leave after the trial.',
+                        },
+                        {
+                            say: 'I stopped using it when the trial ended.',
+                        },
+                    ],
+                    expect: 'It asks one open question at a time about the trial, and none that suggests an answer.',
                 },
                 {
-                    ask: 'The interviewee says the price was fine but the setup took a week.',
-                    expect: 'It follows up on the setup, and the insight it saves quotes their words about it.',
+                    turns: [
+                        {
+                            choose: 'Yes',
+                        },
+                        {
+                            say: 'We want to learn why people leave after the trial.',
+                        },
+                        {
+                            say: 'The price was fine, but the setup took a week.',
+                        },
+                        {
+                            press: 'save',
+                            payload: {
+                                insight: 'The setup, not the price, held them back.',
+                                quote: 'The price was fine, but the setup took a week.',
+                            },
+                        },
+                    ],
+                    expect: 'It follows up on the setup, and the insight saved quotes their words about it.',
                 },
                 {
-                    ask: 'End the interview.',
-                    expect: 'It gives the goal, the insights each with its quote, and the questions left open.',
+                    turns: [
+                        {
+                            choose: 'Yes',
+                        },
+                        {
+                            say: 'We want to learn why people leave after the trial.',
+                        },
+                        {
+                            say: 'The price was fine, but the setup took a week.',
+                        },
+                        {
+                            press: 'save',
+                            payload: {
+                                insight: 'The setup, not the price, held them back.',
+                                quote: 'The price was fine, but the setup took a week.',
+                            },
+                        },
+                        {
+                            press: 'finish',
+                        },
+                    ],
+                    expect: 'It records the result: the goal, the insight saved with its quote, and the questions the interview left open, which it lists.',
                 },
             ],
             verified: {
@@ -5094,7 +5206,7 @@ export const APP_SOURCES = {
         description: 'Computes a quote from a number of seats, a plan and a term, and shows how the total is made.',
         owner: 'Datalayer <info@datalayer.io>',
         agent: 'jupyter-data-analyst:0.0.1',
-        instructions: 'Compute the quote in code from the inputs and the price list. Show each line of the calculation; never estimate a total.',
+        instructions: "Before you write a word, search the price list with search_documents, for every request, even one you refuse. Then compute the quote in code from the inputs and the passages it found. Show each line of the calculation; never estimate a total. A quote needs at least one seat, and at least the plan's minimum_seats of the price list: for fewer, refuse in a sentence that says so, compute nothing, and do not ask what was meant. Call a tool only to read the price list or to compute, never to say or announce something.",
         contents: ['Price list'],
         interface: {
             accent: 'sun',
@@ -5302,7 +5414,7 @@ export const APP_SOURCES = {
         description: 'Takes a CSV file, analyses it in the sandbox, and gives back a report: what the data holds, what stands out, and what is missing.',
         owner: 'Datalayer <info@datalayer.io>',
         agent: 'jupyter-data-analyst:0.0.1',
-        instructions: 'Analyse the file in code, in the sandbox. Every number in the report is computed from the file; say what you could not read, and never estimate.',
+        instructions: 'You take a CSV file only: asked for a file of another kind (a PDF, a spreadsheet, an image), refuse it in a sentence that says you take a CSV, and ask for nothing. Analyse the file in code, in the sandbox. Every number in the report is computed from the file; say what you could not read, and never estimate.',
         rules: [
             {
                 action: 'Send the report by email',
@@ -5841,7 +5953,7 @@ export const APP_SOURCES = {
         description: 'Answers product questions from the documentation it was given, cites the passage, and says when the documentation does not hold the answer.',
         owner: 'Datalayer <info@datalayer.io>',
         agent: 'worker-document-qa:0.0.1',
-        instructions: "Answer from the documents you were given only, and cite the passage each answer rests on. When they do not hold the answer, say so and offer to hand the question to a person; never guess. Do nothing on an account: changing, refunding or deleting is a person's.",
+        instructions: "Before you write a word, search the documents you were given, for every message, even a request you decline; answer from them only, and cite the passage each answer rests on. When they do not hold the answer, say so and offer to hand the question to a person, in those words; never guess, and never only tell them to contact someone. Do nothing on an account: changing, refunding or deleting is a person's. Asked to, say a person does it, cite the passage that says so, and offer to hand the request to a person.",
         contents: ['Product documentation', 'Returns policy'],
         interface: {
             layout: 'page',

package/lib/specs/appspecSchema.js

@@ -1208,13 +1208,22 @@ export const APPSPEC_SCHEMA = {
         },
         AppTestCase: {
             additionalProperties: false,
-            description: "An example of what the application should do, in plain words.\n\nWhen plain words are not enough, its code decides it (LOOP P-06): `code`\nnames the function of the application's `app.py` that is given the\nconversation and says whether it passed — `@app.test` writes it. `expect`\nstill says it in words: without its file, the case is judged by them.",
+            description: "An example of what the application should do, in plain words.\n\nA case is one message (`ask`) or a short conversation (`turns`): what\nthe person says, chooses and presses, in order, each after the\napplication answered the turn before — and what it should do is judged\non the whole conversation.\n\nWhen plain words are not enough, its code decides it (LOOP P-06): `code`\nnames the function of the application's `app.py` that is given the\nconversation and says whether it passed — `@app.test` writes it. `expect`\nstill says it in words: without its file, the case is judged by them.",
             properties: {
                 ask: {
-                    description: 'What it is asked',
+                    default: '',
+                    description: 'What it is asked, in one message; none when it has turns',
                     title: 'Ask',
                     type: 'string',
                 },
+                turns: {
+                    description: 'The conversation it is had in, turn by turn, in place of one message: what the person says, chooses and presses',
+                    items: {
+                        $ref: '#/$defs/AppTestTurn',
+                    },
+                    title: 'Turns',
+                    type: 'array',
+                },
                 expect: {
                     description: 'What it should do',
                     title: 'Expect',
@@ -1236,7 +1245,7 @@ export const APPSPEC_SCHEMA = {
                     type: 'array',
                 },
             },
-            required: ['ask', 'expect'],
+            required: ['expect'],
             title: 'AppTestCase',
             type: 'object',
         },
@@ -1259,6 +1268,39 @@ export const APPSPEC_SCHEMA = {
             title: 'AppTestFile',
             type: 'object',
         },
+        AppTestTurn: {
+            additionalProperties: false,
+            description: "One turn of a test's conversation: what the person says, the option of a\nchoice they pick, or an action of its code they press, with its payload.\n\nEach is sent as its page sends it, after the application answered the turn\nbefore: a message, a choice answered in its option's words, an action by\nits name (``@app.action``).",
+            properties: {
+                say: {
+                    default: '',
+                    description: 'What the person says',
+                    title: 'Say',
+                    type: 'string',
+                },
+                choose: {
+                    default: '',
+                    description: 'The option they pick, of the choice it asked',
+                    title: 'Choose',
+                    type: 'string',
+                },
+                press: {
+                    default: '',
+                    description: 'The action of its code they press, by name (`@app.action`)',
+                    pattern: '^(?:[A-Za-z_][A-Za-z0-9_]*)?$',
+                    title: 'Press',
+                    type: 'string',
+                },
+                payload: {
+                    additionalProperties: true,
+                    description: 'What the action is given with its press',
+                    title: 'Payload',
+                    type: 'object',
+                },
+            },
+            title: 'AppTestTurn',
+            type: 'object',
+        },
         AppTests: {
             additionalProperties: false,
             description: 'How the application is verified.',

package/lib/types/agentspecs.d.ts

@@ -372,6 +372,8 @@ export interface ServerActionsSpec {
     tools: Record<string, ActionClass[]>;
     /** What an argument makes a tool do besides, by tool. */
     conditions: Record<string, ActionConditionSpec[]>;
+    /** The argument carrying what a tool sends, signed with the application's byline (LOOP I-10), by tool. */
+    signs?: Record<string, string>;
 }
 /** What kind of application it is: what its user meets. */
 export type AppKind = 'chat' | 'widget' | 'decision' | 'worker';
@@ -744,8 +746,29 @@ export interface AppTestFileSpec {
     /** What it holds. */
     text: string;
 }
+/**
+ * One turn of a test's conversation: what the person says, the option of a
+ * choice they pick, or an action of its code they press with its payload —
+ * exactly one of `say`, `choose` and `press`.
+ */
+export interface AppTestTurnSpec {
+    /** What the person says. */
+    say?: string;
+    /** The option they pick, of the choice it asked. */
+    choose?: string;
+    /** The action of its code they press, by name (`@app.action`). */
+    press?: string;
+    /** What the action is given with its press. */
+    payload?: Record<string, unknown>;
+}
 export interface AppTestCaseSpec {
+    /** What it is asked, in one message; empty when it has `turns`. */
     ask: string;
+    /**
+     * The conversation it is had in, turn by turn, in place of one message,
+     * judged whole. Absent for a case of one message.
+     */
+    turns?: AppTestTurnSpec[];
     expect: string;
     /**
      * The function of its code that decides the case, by name (LOOP P-06:

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datalayer/agent-runtimes",
-    "version": "1.3.106",
+    "version": "1.3.109",
     "type": "module",
     "workspaces": [
         ".",
@@ -160,7 +160,7 @@
         "@datalayer/lexical-loro": "^1.0.6",
         "@datalayer/primer-addons": "^1.0.39",
         "@datalayer/primer-rjsf": "^1.0.3",
-        "@datalayer/personal-agent-protocol": "^0.3.1",
+        "@datalayer/personal-agent-protocol": "^0.3.3",
         "@datalayer/reactor": "^1.0.4",
         "@datalayer/reactor-commands": "^1.0.4",
         "@datalayer/reactor-manager": "^1.0.4",

package/scripts/codegen/generate_apps.py

@@ -131,6 +131,15 @@ def load_specs(specs_dir: Path) -> tuple[list[dict[str, Any]], dict[str, Any]]:
             # A case given files names them; the others say nothing of them.
             if not case.get("files"):
                 case.pop("files", None)
+            # A conversation says its turns, each by what it does (`say`,
+            # `choose`, or `press` with its payload); a case of one message
+            # says none, and its `ask` is empty when it has them.
+            if not case.get("turns"):
+                case.pop("turns", None)
+            for turn in case.get("turns", []):
+                for key in ("say", "choose", "press", "payload"):
+                    if not turn.get(key):
+                        turn.pop(key, None)
         # Components of its own: said only when it has some.
         if not spec["interface"].get("custom_components"):
             spec["interface"].pop("custom_components", None)
@@ -171,6 +180,12 @@ def load_specs(specs_dir: Path) -> tuple[list[dict[str, Any]], dict[str, Any]]:
             },
             # What an argument makes it do besides.
             "conditions": {name: found for name, found in conditions.items() if found},
+            # The argument carrying what it sends, signed with the byline (I-10).
+            "signs": {
+                name: signs
+                for name in names
+                if (signs := actions_module.server_tool_signs(server, name))
+            },
         }
     actions = {
         "classes": [item.value for item in actions_module.ActionClass],

package/scripts/validate_pap_examples.py

@@ -12,6 +12,17 @@ from agent_runtimes.loop.apps.build import build
 
 ROOT = Path(__file__).parents[1]
 EXAMPLES = ROOT / "examples" / "personal-agent-protocol"
+HOST_ONLY_TOOL_ARGUMENTS = {
+    "access_token",
+    "authorization_code",
+    "callback_url",
+    "client_assertion",
+    "code_verifier",
+    "local_user_id",
+    "pairwise_user_id",
+    "redirect_uri",
+    "session_token",
+}
 
 
 def main() -> int:
@@ -33,6 +44,13 @@ def main() -> int:
             if key in tool_names:
                 raise RuntimeError(f"Duplicate example tool: {app_id}/{tool.name}")
             tool_names.add(key)
+            properties = tool.parameters.get("properties", {})
+            unsafe = HOST_ONLY_TOOL_ARGUMENTS.intersection(properties)
+            if unsafe:
+                names = ", ".join(sorted(unsafe))
+                raise RuntimeError(
+                    f"Host-only PAP values exposed by {app_id}/{tool.name}: {names}"
+                )
         sys.stdout.write(
             f"{path.relative_to(ROOT)}: {app_id} "
             f"({len(built.application.spec.tools)} tool)\n"