taskcheck 1.5.2__tar.gz → 1.6.0__tar.gz

{taskcheck-1.5.2/taskcheck.egg-info → taskcheck-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taskcheck
-Version: 1.5.2
+Version: 1.6.0
 Summary: Automatic scheduler for taskwarrior
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -13,8 +13,6 @@ Requires-Dist: random-unicode-emoji>=2.8
 Requires-Dist: requests>=2.32.3
 Requires-Dist: rich>=13.9.4
 
-![immagine](https://github.com/user-attachments/assets/27b83bb1-7a50-4923-a453-0a958fbe11ed)
-
 A Taskwarrior scheduler for people who want a realistic plan, not a manual to-do list.
 It turns tasks, working hours, and calendar blocks into an actionable schedule — then keeps due dates visible.
 
@@ -23,6 +21,7 @@ Use it if you want to:
 - fit tasks into real availability
 - be sure your long-time plan won't go overdue
 - keep Taskwarrior as the source of truth
+- handle your time across multiple tasks carried on by LLMs
 
 > [!IMPORTANT]
 > This repo is actively maintained again
@@ -30,7 +29,7 @@ Use it if you want to:
 ## Features
 
 - ✨ Auto-schedule tasks from working hours + calendar blocks
-- 🧭 Support complex working-hour maps
+- 🧠 Schedule agent-assisted tasks alongside your own, based on how much supervision they need
 - ⏱️ Consider urgency, due dates, and dependencies
 - 🧪 Persisted dry-run previews for reports and timelines
 - ↩️ Undo the latest schedule update
@@ -41,19 +40,16 @@ Use it if you want to:
 - 🎨 Report styling with emoji and extra attributes
 - 🗓️ Block time with iCal or Google Calendar, including all-day events
 
-## Quick start
+![Dry-run schedule and report](docs/images/dry-run-report.png)
 
-1. `pipx install taskcheck`
-2. `taskcheck --install` ← setup only
-3. add `estimated` + `time_map` UDAs
-4. edit `~/.config/task/taskcheck.toml` (see [Reference](#Reference))
-5. `taskcheck --schedule`
-6. `taskcheck --undo` restores the scheduling fields changed by the latest run
+![Daily timeline](docs/images/timeline-day.png)
 
 ## How it works
 
-Taskcheck reads your pending and waiting tasks, estimates when each one can be worked on, and writes back a schedule.
-It respects:
+Taskcheck reads your pending and waiting tasks, estimates when each one can be worked on, and writes
+back a schedule. For tasks tagged `+agent`, it treats `estimated` as the agent's work time and
+`agent_weight` as the percentage of that time needing your attention. It respects:
+
 - your working hours
 - task duration estimates
 - calendar events and vacations from iCal / Google Calendar
@@ -64,10 +60,21 @@ It updates Taskwarrior with:
 - `completion_date` → when work is expected to finish
 - a warning when a task will miss its due date
 
+## Quick start
+
+1. `pipx install taskcheck`
+2. `taskcheck --install` ← setup only: registers required Taskwarrior settings  inyour taskwarrior config file and offers to create the
+   config file; it does not schedule tasks.
+3. edit `~/.config/task/taskcheck.toml` (see [Reference](#Reference))
+4. tune your tasks: add `estimated`, `time_map`, `agent_weight` UDAs and the `+agent` tag (`time_map` and `agent_weight` may use the default value defined in the Taskwarrior settings)
+5. `taskcheck --schedule`
+6. `taskcheck --undo` restores the scheduling fields changed by the latest run
+
 ### Required UDAs
 
 - `estimated`: expected duration in hours
 - `time_map`: which working-hour profile applies to the task, for example `work` or `weekend`
+- `agent_weight`: required for `+agent` tasks; the percentage (0–100) of agent work time that needs your attention. It defaults to 25 when using `taskcheck --install`.
 
 Example:
 
@@ -77,6 +84,20 @@ monday = [[9, 12.30], [14, 17]]
 tuesday = [[9, 12.30], [14, 17]]
 ```
 
+### Agent tasks and mixed blocks
+
+Mark a task `+agent` when a computer helper will do the work, and set `agent_weight` to show what
+percentage of its work time needs your attention. For example, `10` means you spend about 10 minutes
+interacting with the agent for each hour the agent works. Taskcheck can plan several agent jobs at
+once, fill the time left with your own tasks, and respect waiting dates and dependencies.
+
+```bash
+task add "Implement API" +agent estimated:5h agent_weight:10
+task add "Review results" estimated:1h
+```
+
+Run `taskcheck --install` to register the `agent_weight` Taskwarrior UDA.
+
 ### Reports and timelines
 
 - `taskcheck -r today` → tasks planned for today
@@ -84,9 +105,15 @@ tuesday = [[9, 12.30], [14, 17]]
 - `taskcheck --timeline 1w` → automatic day/week/month timeline for the next week
 - `taskcheck --timeline eom --zoom week` → weekly timeline through month end
 
-Create a preview with `taskcheck --schedule --dry-run`. It does not update Taskwarrior; instead, it saves the generated schedule to the Taskwarrior data directory. Reuse it with `taskcheck --report today --dry-run` or `taskcheck --timeline 1w --dry-run`.
+Create a preview with `taskcheck --schedule --dry-run`. It does not update Taskwarrior; instead, it
+saves the generated schedule to the Taskwarrior data directory. Reuse it with `taskcheck --report
+today --dry-run` or `taskcheck --timeline 1w --dry-run`.
 
-Timeline rows follow dotted project levels such as `work.client`. Without `--zoom`, the most detailed view that fits the terminal width is selected: day, then week, then month. The track uses `▶` for a start, `━` for work, `◀` for an end, and `◆` for a deadline. Thin, heavy, and double rules separate days, weeks, and months. Project colors are deterministic and adapt to light or dark terminals through OSC 11, with config and environment fallbacks.
+Timeline rows follow dotted project levels such as `work.client`. Without `--zoom`, the most
+detailed view that fits the terminal width is selected: day, then week, then month. The track uses
+`▶` for a start, `━` for work, `◀` for an end, and `◆` for a deadline. Thin, heavy, and double rules
+separate days, weeks, and months. Project colors are deterministic and adapt to light or dark
+terminals through OSC 11, with config and environment fallbacks.
 
 ## Reference
 

{taskcheck-1.5.2 → taskcheck-1.6.0}/README.md

@@ -1,5 +1,3 @@
-![immagine](https://github.com/user-attachments/assets/27b83bb1-7a50-4923-a453-0a958fbe11ed)
-
 A Taskwarrior scheduler for people who want a realistic plan, not a manual to-do list.
 It turns tasks, working hours, and calendar blocks into an actionable schedule — then keeps due dates visible.
 
@@ -8,6 +6,7 @@ Use it if you want to:
 - fit tasks into real availability
 - be sure your long-time plan won't go overdue
 - keep Taskwarrior as the source of truth
+- handle your time across multiple tasks carried on by LLMs
 
 > [!IMPORTANT]
 > This repo is actively maintained again
@@ -15,7 +14,7 @@ Use it if you want to:
 ## Features
 
 - ✨ Auto-schedule tasks from working hours + calendar blocks
-- 🧭 Support complex working-hour maps
+- 🧠 Schedule agent-assisted tasks alongside your own, based on how much supervision they need
 - ⏱️ Consider urgency, due dates, and dependencies
 - 🧪 Persisted dry-run previews for reports and timelines
 - ↩️ Undo the latest schedule update
@@ -26,19 +25,16 @@ Use it if you want to:
 - 🎨 Report styling with emoji and extra attributes
 - 🗓️ Block time with iCal or Google Calendar, including all-day events
 
-## Quick start
+![Dry-run schedule and report](docs/images/dry-run-report.png)
 
-1. `pipx install taskcheck`
-2. `taskcheck --install` ← setup only
-3. add `estimated` + `time_map` UDAs
-4. edit `~/.config/task/taskcheck.toml` (see [Reference](#Reference))
-5. `taskcheck --schedule`
-6. `taskcheck --undo` restores the scheduling fields changed by the latest run
+![Daily timeline](docs/images/timeline-day.png)
 
 ## How it works
 
-Taskcheck reads your pending and waiting tasks, estimates when each one can be worked on, and writes back a schedule.
-It respects:
+Taskcheck reads your pending and waiting tasks, estimates when each one can be worked on, and writes
+back a schedule. For tasks tagged `+agent`, it treats `estimated` as the agent's work time and
+`agent_weight` as the percentage of that time needing your attention. It respects:
+
 - your working hours
 - task duration estimates
 - calendar events and vacations from iCal / Google Calendar
@@ -49,10 +45,21 @@ It updates Taskwarrior with:
 - `completion_date` → when work is expected to finish
 - a warning when a task will miss its due date
 
+## Quick start
+
+1. `pipx install taskcheck`
+2. `taskcheck --install` ← setup only: registers required Taskwarrior settings  inyour taskwarrior config file and offers to create the
+   config file; it does not schedule tasks.
+3. edit `~/.config/task/taskcheck.toml` (see [Reference](#Reference))
+4. tune your tasks: add `estimated`, `time_map`, `agent_weight` UDAs and the `+agent` tag (`time_map` and `agent_weight` may use the default value defined in the Taskwarrior settings)
+5. `taskcheck --schedule`
+6. `taskcheck --undo` restores the scheduling fields changed by the latest run
+
 ### Required UDAs
 
 - `estimated`: expected duration in hours
 - `time_map`: which working-hour profile applies to the task, for example `work` or `weekend`
+- `agent_weight`: required for `+agent` tasks; the percentage (0–100) of agent work time that needs your attention. It defaults to 25 when using `taskcheck --install`.
 
 Example:
 
@@ -62,6 +69,20 @@ monday = [[9, 12.30], [14, 17]]
 tuesday = [[9, 12.30], [14, 17]]
 ```
 
+### Agent tasks and mixed blocks
+
+Mark a task `+agent` when a computer helper will do the work, and set `agent_weight` to show what
+percentage of its work time needs your attention. For example, `10` means you spend about 10 minutes
+interacting with the agent for each hour the agent works. Taskcheck can plan several agent jobs at
+once, fill the time left with your own tasks, and respect waiting dates and dependencies.
+
+```bash
+task add "Implement API" +agent estimated:5h agent_weight:10
+task add "Review results" estimated:1h
+```
+
+Run `taskcheck --install` to register the `agent_weight` Taskwarrior UDA.
+
 ### Reports and timelines
 
 - `taskcheck -r today` → tasks planned for today
@@ -69,9 +90,15 @@ tuesday = [[9, 12.30], [14, 17]]
 - `taskcheck --timeline 1w` → automatic day/week/month timeline for the next week
 - `taskcheck --timeline eom --zoom week` → weekly timeline through month end
 
-Create a preview with `taskcheck --schedule --dry-run`. It does not update Taskwarrior; instead, it saves the generated schedule to the Taskwarrior data directory. Reuse it with `taskcheck --report today --dry-run` or `taskcheck --timeline 1w --dry-run`.
+Create a preview with `taskcheck --schedule --dry-run`. It does not update Taskwarrior; instead, it
+saves the generated schedule to the Taskwarrior data directory. Reuse it with `taskcheck --report
+today --dry-run` or `taskcheck --timeline 1w --dry-run`.
 
-Timeline rows follow dotted project levels such as `work.client`. Without `--zoom`, the most detailed view that fits the terminal width is selected: day, then week, then month. The track uses `▶` for a start, `━` for work, `◀` for an end, and `◆` for a deadline. Thin, heavy, and double rules separate days, weeks, and months. Project colors are deterministic and adapt to light or dark terminals through OSC 11, with config and environment fallbacks.
+Timeline rows follow dotted project levels such as `work.client`. Without `--zoom`, the most
+detailed view that fits the terminal width is selected: day, then week, then month. The track uses
+`▶` for a start, `━` for work, `◀` for an end, and `◆` for a deadline. Thin, heavy, and double rules
+separate days, weeks, and months. Project colors are deterministic and adapt to light or dark
+terminals through OSC 11, with config and environment fallbacks.
 
 ## Reference
 

{taskcheck-1.5.2 → taskcheck-1.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "taskcheck"
-version = "1.5.2"
+version = "1.6.0"
 description = "Automatic scheduler for taskwarrior"
 readme = "README.md"
 requires-python = ">=3.11"

taskcheck-1.6.0/taskcheck/agent_blocks.py

@@ -0,0 +1,160 @@
+"""Plan mixed agent/human work inside an ordinary Taskcheck block.
+
+All durations are hours. Agent estimates describe elapsed execution time while
+agent_weight is the percentage of that time needing human interaction. A block
+consumes its full elapsed duration from the calendar, not the sum of the task
+estimates. Internal allocations never create scheduling sub-blocks.
+"""
+
+from datetime import datetime
+from math import isfinite
+
+from taskcheck.common import hours_to_decimal
+
+_EPSILON = 1e-9
+
+
+def get_agent_weight(task):
+    """Return human-interaction fraction for +agent tasks, else None.
+
+    A tagged task must specify a percentage from 0 to 100. In particular,
+    missing weights must not silently imply free, infinite parallelism.
+    """
+    if "agent" not in (task.get("tags") or []):
+        return None
+    try:
+        weight = float(task["agent_weight"])
+    except (KeyError, TypeError, ValueError) as exc:
+        raise ValueError(
+            f"Task {task.get('id', task.get('uuid'))}: +agent requires a numeric agent_weight"
+        ) from exc
+    if not isfinite(weight) or not 0 <= weight <= 100:
+        raise ValueError(
+            f"Task {task.get('id', task.get('uuid'))}: agent_weight must be between 0 and 100"
+        )
+    return weight / 100
+
+
+def _eligible(info, pending, date):
+    if any(dep in pending for dep in info["task"].get("depends", [])):
+        return False
+    wait = info["task"].get("wait")
+    if wait and date <= datetime.strptime(wait, "%Y%m%dT%H%M%SZ").date():
+        return False
+    return True
+
+
+def _max_allocation(info, day_offset, block_hours):
+    return min(
+        float(info["remaining_hours"]),
+        float(info["task_time_map"][day_offset]),
+        block_hours,
+    )
+
+
+def allocate_agent_block(
+    tasks_remaining, sorted_task_ids, day_offset, day_remaining_hours, date, anchor_uuid
+):
+    """Allocate one block anchored by an eligible agent task.
+
+    Returns (elapsed_hours, {uuid: allocated_task_hours}), and mutates the
+    selected task states in-place. None of the individual allocations is a
+    calendar sub-block. All agents run within the same elapsed block; human
+    work consumes interaction time left unused by the agents.
+
+    Tasks which depend on anything pending *at block start* cannot join this
+    same block, even if that prerequisite finishes within it.
+    """
+    anchor = tasks_remaining[anchor_uuid]
+    if get_agent_weight(anchor["task"]) is None:
+        return 0, {}
+    pending = set(tasks_remaining)
+    if not _eligible(anchor, pending, date):
+        return 0, {}
+    block_hours = min(
+        day_remaining_hours,
+        hours_to_decimal(float(anchor["task"].get("min_block", 2))),
+    )
+    if block_hours <= _EPSILON:
+        return 0, {}
+
+    allocations = {}
+    human_budget = block_hours
+    agent_order = [anchor_uuid] + [uuid for uuid in sorted_task_ids if uuid != anchor_uuid]
+    for uuid in agent_order:
+        info = tasks_remaining.get(uuid)
+        if info is None:
+            continue
+        weight = get_agent_weight(info["task"])
+        if weight is None or not _eligible(info, pending, date):
+            continue
+        agent_cap = min(
+            block_hours,
+            hours_to_decimal(float(info["task"].get("min_block", 2))),
+        )
+        duration = _max_allocation(info, day_offset, agent_cap)
+        if weight > 0:
+            duration = min(duration, max(human_budget, 0) / weight)
+        if duration <= _EPSILON:
+            continue
+        allocations[uuid] = duration
+        human_budget = max(0, human_budget - weight * duration)
+
+    # The anchor must have actual execution time; a zero-length block is invalid.
+    if anchor_uuid not in allocations:
+        return 0, {}
+
+    for uuid in sorted_task_ids:
+        info = tasks_remaining.get(uuid)
+        if info is None or get_agent_weight(info["task"]) is not None:
+            continue
+        if not _eligible(info, pending, date):
+            continue
+        # Deliberately allow sub-min_block *allocations*, but only in a mixed
+        # block. Standalone human scheduling stays in the legacy path.
+        # Honor task-specific chunk caps while allowing allocations *smaller*
+        # than that cap only within this mixed block.
+        human_cap = min(
+            human_budget, hours_to_decimal(float(info["task"].get("min_block", 2)))
+        )
+        duration = _max_allocation(info, day_offset, human_cap)
+        if duration <= _EPSILON:
+            continue
+        allocations[uuid] = duration
+        human_budget = max(0, human_budget - duration)
+        if human_budget <= _EPSILON:
+            break
+
+    # Charge only elapsed calendar time actually needed. Otherwise a short
+    # agent finishing alone would artificially consume a whole min_block.
+    # Interaction and human work must fit inside this elapsed interval, while
+    # all agent executions may overlap.
+    interaction_hours = sum(
+        duration * get_agent_weight(tasks_remaining[uuid]["task"])
+        if get_agent_weight(tasks_remaining[uuid]["task"]) is not None
+        else duration
+        for uuid, duration in allocations.items()
+    )
+    elapsed_hours = max(
+        interaction_hours,
+        *(
+            duration
+            for uuid, duration in allocations.items()
+            if get_agent_weight(tasks_remaining[uuid]["task"]) is not None
+        ),
+    )
+
+    date_str = date.isoformat()
+    for uuid, duration in allocations.items():
+        info = tasks_remaining[uuid]
+        if not info["scheduling"]:
+            info["started"] = True
+        info["remaining_hours"] = max(0, info["remaining_hours"] - duration)
+        # Cached time-map lists may be shared by different tasks; the mutable
+        # per-task remaining availability must not alias another task.
+        info["task_time_map"] = list(info["task_time_map"])
+        info["task_time_map"][day_offset] = max(
+            0, info["task_time_map"][day_offset] - duration
+        )
+        info["scheduling"][date_str] = info["scheduling"].get(date_str, 0) + duration
+    return elapsed_hours, allocations

{taskcheck-1.5.2 → taskcheck-1.6.0}/taskcheck/common.py

@@ -148,7 +148,25 @@ def hours_to_pdth(hours):
 def get_long_range_time_map(
     time_maps, time_map_names, days_ahead, calendars, verbose=False
 ):
-    key = ",".join(time_map_names)
+    # The cache must distinguish both the horizon and the input configuration.
+    # Otherwise a previous schedule (possibly with a different time map or
+    # calendar) can silently give tasks stale daily availability.
+    key = (
+        tuple(time_map_names),
+        days_ahead,
+        datetime.today().date(),
+        json.dumps(
+            {name: time_maps[name] for name in time_map_names},
+            sort_keys=True,
+            default=str,
+        ),
+        json.dumps(
+            calendars,
+            sort_keys=True,
+            default=lambda value: value.isoformat()
+            if hasattr(value, "isoformat") else str(value),
+        ),
+    )
     if key in long_range_time_map:
         task_time_map = long_range_time_map[key]
     else:

{taskcheck-1.5.2 → taskcheck-1.6.0}/taskcheck/install.py

@@ -63,6 +63,9 @@ def install():
         ("uda.min_block.type", "numeric"),
         ("uda.min_block.label", "Minimum Time Block"),
         ("uda.min_block.default", "2"),
+        ("uda.agent_weight.type", "numeric"),
+        ("uda.agent_weight.label", "Agent Weight (%)"),
+        ("uda.agent_weight.default", "25"),
         ("recurrence.confirmation", "no"),
     ]
 
@@ -120,7 +123,7 @@ def install():
         """
 _________________________________________________________________________________________
 Required configuration for taskcheck includes:
-- 3 UDA fields 
+- Taskwarrior UDAs, including `agent_weight` for +agent tasks
 - turning off confirmation for recurring tasks 
 
 Do you want to continue? [y/N] """

{taskcheck-1.5.2 → taskcheck-1.6.0}/taskcheck/parallel.py

@@ -6,6 +6,8 @@ from datetime import datetime, timedelta
 
 from rich.table import Table
 
+from taskcheck.agent_blocks import allocate_agent_block, get_agent_weight
+
 from taskcheck.undo import create_undo_backup
 from taskcheck.common import (
     AVOID_STATUS,
@@ -330,11 +332,14 @@ def initialize_task_info(tasks, time_maps, days_ahead, urgency_coefficients, cal
             continue
         if "estimated" not in task or "time_map" not in task:
             continue
+        get_agent_weight(task)  # Validate +agent tasks before scheduling.
         estimated_hours = pdth_to_hours(task["estimated"])
         time_map_names = task["time_map"].split(",")
         task_time_map, today_used_hours = get_long_range_time_map(
             time_maps, time_map_names, days_ahead, calendars
         )
+        # The cache returns a shared list.  Mutations must be task-local.
+        task_time_map = list(task_time_map)
         task_uuid = task["uuid"]
         initial_urgency = float(task.get("urgency", 0))
         estimated_urgency = urgency_estimated(
@@ -415,6 +420,25 @@ def allocate_time_for_day(
                 if verbose:
                     print(f"Skipping task {info['task']['id']} due to wait date {wait}")
                 continue
+            if get_agent_weight(info["task"]) is not None:
+                # Agent tasks overlap in elapsed time.  Charge interactions and
+                # human work to the same block's human-time budget.
+                elapsed, allocations = allocate_agent_block(
+                    tasks_remaining, sorted_task_ids, day_offset,
+                    day_remaining_hours, date, uuid,
+                )
+                if elapsed > 0:
+                    day_remaining_hours -= elapsed
+                    allocated = True
+                    if verbose:
+                        print(f"Allocated mixed block ({elapsed:.2f}h): {allocations}")
+                    for allocated_uuid in allocations:
+                        allocated_info = tasks_remaining[allocated_uuid]
+                        if (allocated_info["remaining_hours"] <= 0
+                            or allocated_info["task_time_map"][day_offset] <= 0):
+                            del tasks_remaining[allocated_uuid]
+                    break
+                continue
             allocation = allocate_time_to_task(info, day_offset, day_remaining_hours)
             if allocation > 0:
                 day_remaining_hours -= allocation

{taskcheck-1.5.2 → taskcheck-1.6.0/taskcheck.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taskcheck
-Version: 1.5.2
+Version: 1.6.0
 Summary: Automatic scheduler for taskwarrior
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -13,8 +13,6 @@ Requires-Dist: random-unicode-emoji>=2.8
 Requires-Dist: requests>=2.32.3
 Requires-Dist: rich>=13.9.4
 
-![immagine](https://github.com/user-attachments/assets/27b83bb1-7a50-4923-a453-0a958fbe11ed)
-
 A Taskwarrior scheduler for people who want a realistic plan, not a manual to-do list.
 It turns tasks, working hours, and calendar blocks into an actionable schedule — then keeps due dates visible.
 
@@ -23,6 +21,7 @@ Use it if you want to:
 - fit tasks into real availability
 - be sure your long-time plan won't go overdue
 - keep Taskwarrior as the source of truth
+- handle your time across multiple tasks carried on by LLMs
 
 > [!IMPORTANT]
 > This repo is actively maintained again
@@ -30,7 +29,7 @@ Use it if you want to:
 ## Features
 
 - ✨ Auto-schedule tasks from working hours + calendar blocks
-- 🧭 Support complex working-hour maps
+- 🧠 Schedule agent-assisted tasks alongside your own, based on how much supervision they need
 - ⏱️ Consider urgency, due dates, and dependencies
 - 🧪 Persisted dry-run previews for reports and timelines
 - ↩️ Undo the latest schedule update
@@ -41,19 +40,16 @@ Use it if you want to:
 - 🎨 Report styling with emoji and extra attributes
 - 🗓️ Block time with iCal or Google Calendar, including all-day events
 
-## Quick start
+![Dry-run schedule and report](docs/images/dry-run-report.png)
 
-1. `pipx install taskcheck`
-2. `taskcheck --install` ← setup only
-3. add `estimated` + `time_map` UDAs
-4. edit `~/.config/task/taskcheck.toml` (see [Reference](#Reference))
-5. `taskcheck --schedule`
-6. `taskcheck --undo` restores the scheduling fields changed by the latest run
+![Daily timeline](docs/images/timeline-day.png)
 
 ## How it works
 
-Taskcheck reads your pending and waiting tasks, estimates when each one can be worked on, and writes back a schedule.
-It respects:
+Taskcheck reads your pending and waiting tasks, estimates when each one can be worked on, and writes
+back a schedule. For tasks tagged `+agent`, it treats `estimated` as the agent's work time and
+`agent_weight` as the percentage of that time needing your attention. It respects:
+
 - your working hours
 - task duration estimates
 - calendar events and vacations from iCal / Google Calendar
@@ -64,10 +60,21 @@ It updates Taskwarrior with:
 - `completion_date` → when work is expected to finish
 - a warning when a task will miss its due date
 
+## Quick start
+
+1. `pipx install taskcheck`
+2. `taskcheck --install` ← setup only: registers required Taskwarrior settings  inyour taskwarrior config file and offers to create the
+   config file; it does not schedule tasks.
+3. edit `~/.config/task/taskcheck.toml` (see [Reference](#Reference))
+4. tune your tasks: add `estimated`, `time_map`, `agent_weight` UDAs and the `+agent` tag (`time_map` and `agent_weight` may use the default value defined in the Taskwarrior settings)
+5. `taskcheck --schedule`
+6. `taskcheck --undo` restores the scheduling fields changed by the latest run
+
 ### Required UDAs
 
 - `estimated`: expected duration in hours
 - `time_map`: which working-hour profile applies to the task, for example `work` or `weekend`
+- `agent_weight`: required for `+agent` tasks; the percentage (0–100) of agent work time that needs your attention. It defaults to 25 when using `taskcheck --install`.
 
 Example:
 
@@ -77,6 +84,20 @@ monday = [[9, 12.30], [14, 17]]
 tuesday = [[9, 12.30], [14, 17]]
 ```
 
+### Agent tasks and mixed blocks
+
+Mark a task `+agent` when a computer helper will do the work, and set `agent_weight` to show what
+percentage of its work time needs your attention. For example, `10` means you spend about 10 minutes
+interacting with the agent for each hour the agent works. Taskcheck can plan several agent jobs at
+once, fill the time left with your own tasks, and respect waiting dates and dependencies.
+
+```bash
+task add "Implement API" +agent estimated:5h agent_weight:10
+task add "Review results" estimated:1h
+```
+
+Run `taskcheck --install` to register the `agent_weight` Taskwarrior UDA.
+
 ### Reports and timelines
 
 - `taskcheck -r today` → tasks planned for today
@@ -84,9 +105,15 @@ tuesday = [[9, 12.30], [14, 17]]
 - `taskcheck --timeline 1w` → automatic day/week/month timeline for the next week
 - `taskcheck --timeline eom --zoom week` → weekly timeline through month end
 
-Create a preview with `taskcheck --schedule --dry-run`. It does not update Taskwarrior; instead, it saves the generated schedule to the Taskwarrior data directory. Reuse it with `taskcheck --report today --dry-run` or `taskcheck --timeline 1w --dry-run`.
+Create a preview with `taskcheck --schedule --dry-run`. It does not update Taskwarrior; instead, it
+saves the generated schedule to the Taskwarrior data directory. Reuse it with `taskcheck --report
+today --dry-run` or `taskcheck --timeline 1w --dry-run`.
 
-Timeline rows follow dotted project levels such as `work.client`. Without `--zoom`, the most detailed view that fits the terminal width is selected: day, then week, then month. The track uses `▶` for a start, `━` for work, `◀` for an end, and `◆` for a deadline. Thin, heavy, and double rules separate days, weeks, and months. Project colors are deterministic and adapt to light or dark terminals through OSC 11, with config and environment fallbacks.
+Timeline rows follow dotted project levels such as `work.client`. Without `--zoom`, the most
+detailed view that fits the terminal width is selected: day, then week, then month. The track uses
+`▶` for a start, `━` for work, `◀` for an end, and `◆` for a deadline. Thin, heavy, and double rules
+separate days, weeks, and months. Project colors are deterministic and adapt to light or dark
+terminals through OSC 11, with config and environment fallbacks.
 
 ## Reference
 

{taskcheck-1.5.2 → taskcheck-1.6.0}/taskcheck.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 taskcheck/__main__.py
+taskcheck/agent_blocks.py
 taskcheck/common.py
 taskcheck/dry_run.py
 taskcheck/google_calendar.py
@@ -18,6 +19,8 @@ taskcheck.egg-info/dependency_links.txt
 taskcheck.egg-info/entry_points.txt
 taskcheck.egg-info/requires.txt
 taskcheck.egg-info/top_level.txt
+tests/test_agent_blocks.py
+tests/test_agent_scheduler_integration.py
 tests/test_common.py
 tests/test_google_calendar.py
 tests/test_ical.py

taskcheck-1.6.0/tests/test_agent_blocks.py

@@ -0,0 +1,196 @@
+from datetime import date, timedelta
+
+import pytest
+
+from taskcheck.agent_blocks import allocate_agent_block, get_agent_weight
+
+TODAY = date.today()
+
+
+def task(name, *, agent=False, weight=None, hours=2, urgency=10, depends=(), wait=None, daily=8):
+    record = {"uuid": name, "id": name, "estimated": "PT2H", "min_block": 2}
+    if agent:
+        record["tags"] = ["agent"]
+    if weight is not None:
+        record["agent_weight"] = weight
+    if depends:
+        record["depends"] = list(depends)
+    if wait:
+        record["wait"] = wait
+    return {"task": record, "remaining_hours": hours, "task_time_map": [daily],
+            "scheduling": {}, "started": False, "urgency": urgency}
+
+
+def run(items, order=None, block=2):
+    ordered = order or sorted(items, key=lambda name: -items[name]["urgency"])
+    return allocate_agent_block(items, ordered, 0, block, TODAY, ordered[0])
+
+
+def test_mixed_two_agents_and_short_human_tasks():
+    items = {
+        "a": task("a", agent=True, weight=25),
+        "b": task("b", agent=True, weight=35),
+        "h1": task("h1", hours=.5),
+        "h2": task("h2", hours=.5),
+    }
+    elapsed, selected = run(items, ["a", "b", "h1", "h2"])
+    assert elapsed == 2
+    assert selected == pytest.approx({"a": 2, "b": 2, "h1": .5, "h2": .3})
+    assert items["h1"]["remaining_hours"] == pytest.approx(0)
+    assert items["h2"]["remaining_hours"] == pytest.approx(.2)
+    assert all(set(info["scheduling"]) == {TODAY.isoformat()} for info in items.values())
+
+
+def test_short_agent_duration_consumes_only_actual_interaction():
+    items = {"a": task("a", agent=True, weight=25, hours=1),
+             "h": task("h", hours=2)}
+    elapsed, allocation = run(items, ["a", "h"])
+    assert elapsed == 2
+    assert allocation == pytest.approx({"a": 1, "h": 1.75})
+
+
+def test_full_weight_agent_excludes_human():
+    items = {"a": task("a", agent=True, weight=100),
+             "h": task("h", hours=2)}
+    _, selected = run(items, ["a", "h"])
+    assert selected == {"a": 2}
+    assert items["h"]["remaining_hours"] == 2
+
+
+def test_dependencies_cannot_execute_with_agent_in_same_block():
+    items = {"a": task("a", agent=True, weight=25),
+             "h": task("h", hours=1, depends=["a"]),
+             "other": task("other", hours=1)}
+    _, selected = run(items, ["a", "h", "other"])
+    assert "h" not in selected
+    assert selected["other"] == 1
+
+
+def test_waiting_agent_excluded_even_when_urgent():
+    tomorrow = (TODAY + timedelta(days=1)).strftime("%Y%m%dT%H%M%SZ")
+    items = {"a": task("a", agent=True, weight=25),
+             "b": task("b", agent=True, weight=25, wait=tomorrow),
+             "h": task("h", hours=2)}
+    _, selected = run(items, ["a", "b", "h"])
+    assert selected == pytest.approx({"a": 2, "h": 1.5})
+
+
+def test_daily_availability_limits_agent_and_human():
+    items = {"a": task("a", agent=True, weight=50, daily=.5),
+             "h": task("h", hours=2, daily=.75)}
+    elapsed, selected = run(items, ["a", "h"])
+    assert elapsed == pytest.approx(1)
+    assert selected == pytest.approx({"a": .5, "h": .75})
+
+
+def test_agent_capacity_limits_multiple_agents():
+    items = {"a": task("a", agent=True, weight=80),
+             "b": task("b", agent=True, weight=40)}
+    _, selected = run(items, ["a", "b"])
+    assert selected == pytest.approx({"a": 2, "b": 1})
+
+
+@pytest.mark.parametrize("bad", [None, -1, 101, "bad", float("nan")])
+def test_invalid_weight_is_rejected(bad):
+    t = task("a", agent=True, weight=bad)["task"]
+    with pytest.raises(ValueError, match="agent_weight"):
+        get_agent_weight(t)
+
+
+def test_non_agent_does_not_require_weight():
+    assert get_agent_weight(task("h")["task"]) is None
+
+
+def test_no_real_subblocks_appear_in_scheduling():
+    items = {"a": task("a", agent=True, weight=25), "h": task("h", hours=.5)}
+    _, _ = run(items, ["a", "h"])
+    assert items["a"]["scheduling"] == {TODAY.isoformat(): 2}
+    assert items["h"]["scheduling"] == {TODAY.isoformat(): .5}
+
+
+def test_short_lone_agent_does_not_reserve_unused_calendar_time():
+    items = {"a": task("a", agent=True, weight=25, hours=1)}
+    elapsed, selected = run(items, ["a"])
+    assert selected == {"a": 1}
+    assert elapsed == pytest.approx(1)
+
+
+def test_mixed_block_elapsed_reflects_agents_and_supervision_time():
+    items = {"a": task("a", agent=True, weight=25, hours=1),
+             "h": task("h", hours=1)}
+    elapsed, selected = run(items, ["a", "h"])
+    assert selected == pytest.approx({"a": 1, "h": 1})
+    assert elapsed == pytest.approx(1.25)
+
+
+def test_one_minute_human_task_is_valid_inside_mixed_block():
+    # min_block is a bound on *outer* chunks; it does not apply to human
+    # allocations inside a mixed block.
+    items = {"a": task("a", agent=True, weight=10, hours=2),
+             "h": task("h", hours=1 / 60)}
+    elapsed, selected = run(items, ["a", "h"])
+    assert elapsed == pytest.approx(2)
+    assert selected["h"] == pytest.approx(1 / 60)
+    assert items["h"]["remaining_hours"] == pytest.approx(0)
+
+
+def test_one_minute_agent_can_anchor_mixed_block():
+    items = {"a": task("a", agent=True, weight=10, hours=1 / 60),
+             "h": task("h", hours=.5)}
+    elapsed, selected = run(items, ["a", "h"])
+    assert selected == pytest.approx({"a": 1 / 60, "h": .5})
+    assert elapsed == pytest.approx(.5 + 1 / 600)
+
+
+def test_cached_time_map_is_not_mutated_across_tasks():
+    # get_long_range_time_map caches its list by name in the upstream module.
+    # An independent per-task daily cap is required: a task's execution must
+    # not eat another task's cap just because they share the same profile.
+    items = {"a": task("a", agent=True, weight=10, hours=1),
+             "h": task("h", hours=.5)}
+    original_shared_map = [2.0]
+    items["a"]["task_time_map"] = original_shared_map
+    items["h"]["task_time_map"] = original_shared_map
+    elapsed, selected = run(items, ["a", "h"])
+    assert selected == pytest.approx({"a": 1, "h": .5})
+    assert elapsed == pytest.approx(1)
+    assert items["a"]["task_time_map"] == pytest.approx([1])
+    assert items["h"]["task_time_map"] == pytest.approx([1.5])
+    assert original_shared_map == [2.0]
+
+
+def test_many_mixed_blocks_respect_elapsed_and_human_budget():
+    import random
+    rng = random.Random(765421)
+    for _ in range(500):
+        weights = [rng.uniform(0, 100) for _ in range(rng.randint(1, 6))]
+        items = {
+            f"a{i}": task(f"a{i}", agent=True, weight=w,
+                         hours=rng.uniform(.01, 4), daily=rng.uniform(.1, 3))
+            for i, w in enumerate(weights)
+        }
+        for j in range(rng.randint(0, 5)):
+            items[f"h{j}"] = task(f"h{j}", hours=rng.uniform(.01, 4),
+                                 daily=rng.uniform(.1, 3))
+        originals = {name: data['remaining_hours'] for name, data in items.items()}
+        elapsed, selected = run(items, list(items))
+        assert 0 < elapsed <= 2 + 1e-8
+        interaction = sum(selected.get(name, 0) * (get_agent_weight(info['task']) or 0)
+                          if 'agent' in info['task'].get('tags', [])
+                          else selected.get(name, 0)
+                          for name, info in items.items())
+        assert interaction <= elapsed + 1e-8
+        for name, allocated in selected.items():
+            assert allocated <= originals[name] + 1e-8
+            assert items[name]['remaining_hours'] >= -1e-8
+            if get_agent_weight(items[name]['task']) is not None:
+                assert allocated <= elapsed + 1e-8
+
+
+def test_human_custom_chunk_limit_is_respected_inside_mixed_block():
+    items = {"a": task("a", agent=True, weight=10, hours=2),
+             "h": task("h", hours=3)}
+    items['h']['task']['min_block'] = 0.3  # Original hh.mm convention: 30 minutes.
+    elapsed, selected = run(items, ['a', 'h'])
+    assert elapsed == pytest.approx(2)
+    assert selected['h'] == pytest.approx(.5)

taskcheck-1.6.0/tests/test_agent_scheduler_integration.py

@@ -0,0 +1,153 @@
+"""Integration coverage against taskcheck.parallel's day-allocation loop."""
+from datetime import datetime, timedelta
+
+import pytest
+
+from taskcheck.parallel import UrgencyCoefficients, allocate_time_for_day
+
+
+COEFFS = UrgencyCoefficients({"PT2H": 0}, False, 0, 365, 0, 0)
+
+
+def info(name, *, hours=2, urgency=10, agent=False, weight=None, depends=()):
+    t = {"uuid": name, "id": name, "description": name,
+         "estimated": "PT2H", "min_block": 2}
+    if agent:
+        t["tags"] = ["agent"]
+        t["agent_weight"] = weight
+    if depends:
+        t["depends"] = list(depends)
+    return {"task": t, "remaining_hours": hours,
+            "task_time_map": [2.0, 2.0], "today_used_hours": 0,
+            "scheduling": {}, "urgency": urgency,
+            "estimated_urgency": 0, "age_urgency": 0, "due_urgency": 0,
+            "started": False}
+
+
+def schedule(tasks, monkeypatch):
+    monkeypatch.setattr('taskcheck.parallel.recompute_urgencies', lambda *args, **kwargs: None)
+    allocate_time_for_day(tasks, 1, COEFFS, False, 1)
+    return (datetime.today().date() + timedelta(days=1)).isoformat()
+
+
+def test_mixed_allocation_inside_one_calendar_block(monkeypatch):
+    tasks = {"a": info("a", agent=True, weight=25),
+             "b": info("b", agent=True, weight=35, urgency=9),
+             "h": info("h", hours=.8, urgency=8)}
+    day = schedule(tasks, monkeypatch)
+    assert tasks["a"]["scheduling"] == {day: 2}
+    assert tasks["b"]["scheduling"] == {day: 2}
+    assert tasks["h"]["scheduling"] == pytest.approx({day: .8})
+
+
+def test_more_urgent_human_keeps_exclusive_block(monkeypatch):
+    tasks = {"h": info("h", urgency=20),
+             "a": info("a", agent=True, weight=25, urgency=10)}
+    day = schedule(tasks, monkeypatch)
+    assert tasks["h"]["scheduling"] == {day: 2}
+    assert tasks["a"]["scheduling"] == {}
+
+
+def test_dependencies_wait_for_next_block(monkeypatch):
+    tasks = {"a": info("a", agent=True, weight=25, urgency=20),
+             "dependent": info("dependent", hours=.5, urgency=18, depends=("a",)),
+             "h": info("h", hours=.5, urgency=15)}
+    day = schedule(tasks, monkeypatch)
+    assert tasks["dependent"]["scheduling"] == {}
+    assert tasks["h"]["scheduling"] == {day: .5}
+
+
+def test_five_hour_agent_ten_percent_occupies_two_and_half_blocks(monkeypatch):
+    # estimated:5h = execution time, NOT supervision time.
+    monkeypatch.setattr('taskcheck.parallel.recompute_urgencies', lambda *args, **kwargs: None)
+    agent = info('a', hours=5, agent=True, weight=10)
+    agent['task']['estimated'] = 'PT5H'
+    agent['task_time_map'] = [2.0, 2.0, 2.0, 2.0]
+    allocated_days = []
+    for offset in range(1, 4):
+        allocate_time_for_day({'a': agent}, offset, COEFFS, False, 1)
+        day = (datetime.today().date() + timedelta(days=offset)).isoformat()
+        allocated_days.append(agent['scheduling'].get(day, 0))
+    assert allocated_days == pytest.approx([2, 2, 1])
+    assert sum(allocated_days) == pytest.approx(5)
+    assert sum(allocated_days) * .10 == pytest.approx(.5)
+    assert agent['remaining_hours'] == pytest.approx(0)
+
+
+def test_five_hour_agent_and_four_hour_human_fit_in_five_calendar_hours(monkeypatch):
+    """Regression: estimates are agent wall-time, NOT supervision time."""
+    monkeypatch.setattr('taskcheck.parallel.recompute_urgencies', lambda *args, **kwargs: None)
+    a = info('a', hours=5, agent=True, weight=10, urgency=20)
+    a['task']['estimated'] = 'PT5H'
+    h = info('h', hours=4, urgency=10)
+    for item in (a, h):
+        item['task_time_map'] = [0, 5]
+    task_info = {'a': a, 'h': h}
+    allocate_time_for_day(task_info, 1, COEFFS, False, 1)
+    day = (datetime.today().date() + timedelta(days=1)).isoformat()
+    assert a['scheduling'][day] == pytest.approx(5)
+    assert h['scheduling'][day] == pytest.approx(4)
+    assert a['remaining_hours'] == pytest.approx(0)
+    assert h['remaining_hours'] == pytest.approx(0)
+    # 5h elapsed, with 5h*10%=0.5h supervision + 4h independent work.
+    assert a['scheduling'][day] * .10 + h['scheduling'][day] == pytest.approx(4.5)
+
+
+def test_initialize_task_info_does_not_share_cached_availability(monkeypatch):
+    from taskcheck.parallel import initialize_task_info
+    shared = [3., 3.]
+    monkeypatch.setattr('taskcheck.parallel.get_long_range_time_map',
+                        lambda *args: (shared, 0))
+    tasks = [
+        {'id': 1, 'uuid': 'a', 'estimated': 'PT2H', 'time_map': 'work',
+         'tags': ['agent'], 'agent_weight': 25},
+        {'id': 2, 'uuid': 'h', 'estimated': 'PT2H', 'time_map': 'work'},
+    ]
+    states = initialize_task_info(tasks, {}, 2, COEFFS, [])
+    assert states['a']['task_time_map'] is not states['h']['task_time_map']
+    assert states['a']['task_time_map'] is not shared
+    states['a']['task_time_map'][0] -= 2
+    assert states['h']['task_time_map'] == [3., 3.]
+    assert shared == [3., 3.]
+
+
+def test_initialize_task_info_rejects_missing_agent_weight(monkeypatch):
+    from taskcheck.parallel import initialize_task_info
+    tasks = [{'id': 1, 'uuid': 'a', 'estimated': 'PT2H',
+              'time_map': 'work', 'tags': ['agent']}]
+    with pytest.raises(ValueError, match='agent_weight'):
+        initialize_task_info(tasks, {}, 2, COEFFS, [])
+
+
+def test_availability_cache_is_scoped_to_horizon_and_time_map():
+    """A new schedule must not inherit a stale cached horizon or work profile."""
+    from taskcheck.common import get_long_range_time_map, long_range_time_map
+    long_range_time_map.clear()
+    work = {day: [[9, 17]] for day in
+            ('monday', 'tuesday', 'wednesday', 'thursday', 'friday',
+             'saturday', 'sunday')}
+    try:
+        short, _ = get_long_range_time_map({'work': work}, ['work'], 2, [])
+        long, _ = get_long_range_time_map({'work': work}, ['work'], 3, [])
+        assert len(short) == 2
+        assert len(long) == 3
+        shorter_hours = {day: [[9, 12]] for day in work}
+        changed, _ = get_long_range_time_map(
+            {'work': shorter_hours}, ['work'], 3, [])
+        assert changed == [3., 3., 3.]
+    finally:
+        long_range_time_map.clear()
+
+
+def test_install_registers_agent_weight_uda(monkeypatch):
+    from taskcheck import install as install_module
+    from unittest.mock import Mock
+    apply = Mock()
+    monkeypatch.setattr(install_module, 'apply_config', apply)
+    answers = iter(('yes', 'no', 'no'))
+    monkeypatch.setattr('builtins.input', lambda *args: next(answers))
+    install_module.install()
+    applied = [call.args for call in apply.call_args_list]
+    assert ('uda.agent_weight.type', 'numeric') in applied
+    assert ('uda.agent_weight.label', 'Agent Weight (%)') in applied
+    assert ('uda.agent_weight.default', '25') in applied